<!-- llms.txt: https://workos.com/llms.txt -->

# Users

Read and update the profile of the user the token was issued for.

## Confirm an email change

Confirms an email change using the verification code sent to the new email address. Requires an elevated access token from `verifyCurrentEmail`.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation ConfirmEmailChange($input: ConfirmEmailChangeInput!) {
  confirmEmailChange(input: $input) {
    __typename
    ... on EmailChangeCodeExpired {
      message
    }
    ... on EmailChangeCodeIncorrect {
      message
    }
    ... on EmailChangeCodePreviouslyUsed {
      message
    }
    ... on EmailChangeConfirmed {
      elevatedAccessToken
      expiresAt
      user {
        createdAt
        email
        emailVerified
        firstName
        id
        lastName
        mfaEnabled
        mfaLastUsedAt
        passwordLastUsedAt
        passwordSet
        profilePictureUrl
        updatedAt
      }
    }
    ... on EmailChangeTooManyAttempts {
      message
    }
    ... on EmailManagedByProvider {
      message
    }
    ... on EmailNotAvailable {
      message
    }
    ... on IdentityVerificationExpired {
      message
    }
    ... on IdentityVerificationInvalid {
      message
    }
    ... on InvalidEmail {
      message
    }
    ... on NoPendingEmailChange {
      message
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "confirmEmailChange": {
      "__typename": "EmailChangeCodeExpired",
      "message": "message_example"
    }
  }
}
```

:::

## Get the current user

Returns the currently authenticated user (the subject of the token).

:::code-group

```graphql language="graphql" title="Query" tab="1"
query Me {
  me {
    connectedAccounts {
      email
      firstName
      id
      lastLoginAt
      lastName
      profilePictureUrl
      provider
    }
    createdAt
    email
    emailVerified
    firstName
    id
    lastName
    mfaEnabled
    mfaLastUsedAt
    passwordLastUsedAt
    passwordSet
    profilePictureUrl
    updatedAt
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "me": {
      "connectedAccounts": [
        {
          "email": "email_example",
          "firstName": "firstName_example",
          "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
          "lastLoginAt": "2024-01-01T00:00:00.000Z",
          "lastName": "lastName_example",
          "profilePictureUrl": "profilePictureUrl_example",
          "provider": "AppleOAuth"
        }
      ],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "email": "email_example",
      "emailVerified": true,
      "firstName": "firstName_example",
      "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "lastName": "lastName_example",
      "mfaEnabled": true,
      "mfaLastUsedAt": "2024-01-01T00:00:00.000Z",
      "passwordLastUsedAt": "2024-01-01T00:00:00.000Z",
      "passwordSet": true,
      "profilePictureUrl": "profilePictureUrl_example",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}
```

:::

## Send an email change code

Sends a verification code to the new email address. Requires an elevated access token from `verifyCurrentEmail`. The user must confirm with the code via `confirmEmailChange`.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation SendEmailChange($input: SendEmailChangeInput!) {
  sendEmailChange(input: $input) {
    __typename
    ... on DailyEmailQuotaExceeded {
      message
    }
    ... on EmailChangeNotAvailable {
      message
    }
    ... on EmailChangeSent {
      expiresAt
    }
    ... on EmailManagedByProvider {
      message
    }
    ... on EmailNotAvailable {
      message
    }
    ... on IdentityVerificationExpired {
      message
    }
    ... on IdentityVerificationInvalid {
      message
    }
    ... on InvalidEmail {
      message
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "sendEmailChange": {
      "__typename": "DailyEmailQuotaExceeded",
      "message": "message_example"
    }
  }
}
```

:::

## Send a verification code

Sends a verification code to the user's current email address to prove ownership before changing email.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation SendVerificationCode {
  sendVerificationCode {
    __typename
    ... on DailyEmailQuotaExceeded {
      message
    }
    ... on VerificationCodeSent {
      authenticationChallengeId
      expiresAt
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "sendVerificationCode": {
      "__typename": "DailyEmailQuotaExceeded",
      "message": "message_example"
    }
  }
}
```

:::

## Update a profile

Updates the authenticated user's profile (first name, last name, locale).

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation UpdateProfile($input: UpdateProfileInput!) {
  updateProfile(input: $input) {
    __typename
    ... on ProfileUpdated {
      user {
        createdAt
        email
        emailVerified
        firstName
        id
        lastName
        mfaEnabled
        mfaLastUsedAt
        passwordLastUsedAt
        passwordSet
        profilePictureUrl
        updatedAt
      }
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "updateProfile": {
      "__typename": "InvalidLocale"
    }
  }
}
```

:::

## Get a user

Returns a user by ID, provided they are a member of the token's organization.

:::code-group

```graphql language="graphql" title="Query" tab="1"
query User($id: ID!) {
  user(id: $id) {
    connectedAccounts {
      email
      firstName
      id
      lastLoginAt
      lastName
      profilePictureUrl
      provider
    }
    createdAt
    email
    emailVerified
    firstName
    id
    lastName
    mfaEnabled
    mfaLastUsedAt
    passwordLastUsedAt
    passwordSet
    profilePictureUrl
    updatedAt
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "user": {
      "connectedAccounts": [
        {
          "email": "email_example",
          "firstName": "firstName_example",
          "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
          "lastLoginAt": "2024-01-01T00:00:00.000Z",
          "lastName": "lastName_example",
          "profilePictureUrl": "profilePictureUrl_example",
          "provider": "AppleOAuth"
        }
      ],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "email": "email_example",
      "emailVerified": true,
      "firstName": "firstName_example",
      "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "lastName": "lastName_example",
      "mfaEnabled": true,
      "mfaLastUsedAt": "2024-01-01T00:00:00.000Z",
      "passwordLastUsedAt": "2024-01-01T00:00:00.000Z",
      "passwordSet": true,
      "profilePictureUrl": "profilePictureUrl_example",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}
```

:::

## Verify the current email

Verifies the code sent to the current email address. Returns an elevated access token required for `sendEmailChange` and `confirmEmailChange`.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation VerifyCurrentEmail($input: VerifyCurrentEmailInput!) {
  verifyCurrentEmail(input: $input) {
    __typename
    ... on CurrentEmailVerified {
      elevatedAccessToken
      expiresAt
    }
    ... on VerificationCodeExpired {
      message
    }
    ... on VerificationCodeIncorrect {
      message
    }
    ... on VerificationCodePreviouslyUsed {
      message
    }
    ... on VerificationTooManyAttempts {
      message
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "verifyCurrentEmail": {
      "__typename": "CurrentEmailVerified",
      "elevatedAccessToken": "elevatedAccessToken_example",
      "expiresAt": "expiresAt_example"
    }
  }
}
```

:::

### Mutation confirmEmailChange

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | String! | Yes | The verification code sent to the new email address. |
| `elevatedAccessToken` | String! | Yes | The elevated access token from a successful `verifyCurrentEmail` call. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `EmailChangeCodeExpired` | EmailChangeCodeExpired | The verification code has expired. |
| `EmailChangeCodeIncorrect` | EmailChangeCodeIncorrect | The verification code is incorrect. |
| `EmailChangeCodePreviouslyUsed` | EmailChangeCodePreviouslyUsed | The verification code has already been used. |
| `EmailChangeConfirmed` | EmailChangeConfirmed | The email was changed successfully. |
| `EmailChangeTooManyAttempts` | EmailChangeTooManyAttempts | Too many verification attempts. |
| `EmailManagedByProvider` | EmailManagedByProvider | The email is managed by an identity provider and cannot be changed. |
| `EmailNotAvailable` | EmailNotAvailable | The email address is not available. |
| `IdentityVerificationExpired` | IdentityVerificationExpired | The identity verification has expired. Please verify your current email again. |
| `IdentityVerificationInvalid` | IdentityVerificationInvalid | The identity verification is no longer valid. |
| `InvalidEmail` | InvalidEmail | The provided email address is invalid. |
| `NoPendingEmailChange` | NoPendingEmailChange | There is no pending email change to confirm. |

### Query me

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connectedAccounts` | [ConnectedAccount!]! | An OAuth profile linked to the authenticated user. |
| `createdAt` | DateTime! |  |
| `email` | String! |  |
| `emailVerified` | Boolean! |  |
| `firstName` | String |  |
| `id` | ID! |  |
| `lastName` | String |  |
| `mfaEnabled` | Boolean! | Whether multi-factor authentication (TOTP) is set up for this user. Always `false` when the environment has MFA turned off — use `authenticationSettings.mfaEnabled` to tell the two apart. Only populated on `me`. |
| `mfaLastUsedAt` | DateTime | When MFA was last used to authenticate. Only populated on `me`. |
| `passwordLastUsedAt` | DateTime | When a password was last used to authenticate. Only populated on `me`. |
| `passwordSet` | Boolean! | Whether this user has a password set. Reflects the user regardless of whether the environment allows password authentication; use `authenticationSettings.passwordAuthEnabled` for that. Only populated on `me`. |
| `profilePictureUrl` | String |  |
| `updatedAt` | DateTime! |  |

### Mutation sendEmailChange

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `elevatedAccessToken` | String! | Yes | The elevated access token from a successful `verifyCurrentEmail` call. |
| `newEmail` | String! | Yes | The new email address to change to. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `DailyEmailQuotaExceeded` | DailyEmailQuotaExceeded | Daily verification email quota exceeded. |
| `EmailChangeNotAvailable` | EmailChangeNotAvailable | Email change is not available for this account. |
| `EmailChangeSent` | EmailChangeSent | A verification code was sent to the new email address. |
| `EmailManagedByProvider` | EmailManagedByProvider | The email is managed by an identity provider and cannot be changed. |
| `EmailNotAvailable` | EmailNotAvailable | The email address is not available. |
| `IdentityVerificationExpired` | IdentityVerificationExpired | The identity verification has expired. Please verify your current email again. |
| `IdentityVerificationInvalid` | IdentityVerificationInvalid | The identity verification is no longer valid. |
| `InvalidEmail` | InvalidEmail | The provided email address is invalid. |

### Mutation sendVerificationCode

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `DailyEmailQuotaExceeded` | DailyEmailQuotaExceeded | Daily verification email quota exceeded. |
| `VerificationCodeSent` | VerificationCodeSent | A verification code was sent to the current email address for identity verification. |

### Mutation updateProfile

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `firstName` | String | No | The user's first name. Pass an empty string to clear. |
| `lastName` | String | No | The user's last name. Pass an empty string to clear. |
| `locale` | String | No | The user's locale as a BCP 47 language tag (e.g. 'en-US'). Pass an empty string to clear. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `InvalidLocale` | InvalidLocale | The provided locale is not a valid BCP 47 tag. |
| `ProfileUpdated` | ProfileUpdated | The profile was updated successfully. |

### Query user

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | ID! | Yes |  |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connectedAccounts` | [ConnectedAccount!]! | An OAuth profile linked to the authenticated user. |
| `createdAt` | DateTime! |  |
| `email` | String! |  |
| `emailVerified` | Boolean! |  |
| `firstName` | String |  |
| `id` | ID! |  |
| `lastName` | String |  |
| `mfaEnabled` | Boolean! | Whether multi-factor authentication (TOTP) is set up for this user. Always `false` when the environment has MFA turned off — use `authenticationSettings.mfaEnabled` to tell the two apart. Only populated on `me`. |
| `mfaLastUsedAt` | DateTime | When MFA was last used to authenticate. Only populated on `me`. |
| `passwordLastUsedAt` | DateTime | When a password was last used to authenticate. Only populated on `me`. |
| `passwordSet` | Boolean! | Whether this user has a password set. Reflects the user regardless of whether the environment allows password authentication; use `authenticationSettings.passwordAuthEnabled` for that. Only populated on `me`. |
| `profilePictureUrl` | String |  |
| `updatedAt` | DateTime! |  |

### Mutation verifyCurrentEmail

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `authenticationChallengeId` | ID! | Yes | The authentication challenge ID returned from `sendVerificationCode`. |
| `code` | String! | Yes | The verification code sent to the current email address. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `CurrentEmailVerified` | CurrentEmailVerified | The current email was verified successfully. |
| `VerificationCodeExpired` | VerificationCodeExpired | The verification code has expired. |
| `VerificationCodeIncorrect` | VerificationCodeIncorrect | The verification code is incorrect. |
| `VerificationCodePreviouslyUsed` | VerificationCodePreviouslyUsed | The verification code has already been used. |
| `VerificationTooManyAttempts` | VerificationTooManyAttempts | Too many verification code attempts. |