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

# Authentication

Inspect the environment's authentication settings and manage the signed-in user's passwords, multi-factor factors, passkeys, and active sessions.

## Get authentication settings

The authentication methods the environment allows and the password policy it enforces. Requires a session token.

:::code-group

```graphql language="graphql" title="Query" tab="1"
query AuthenticationSettings {
  authenticationSettings {
    mfaEnabled
    mfaRequired
    passkeyAuthEnabled
    passwordAuthEnabled
    passwordPolicy {
      minimumLength
      minimumStrength
      rejectsBreachedPasswords
      requiresLowercase
      requiresNumber
      requiresSymbol
      requiresUppercase
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "authenticationSettings": {
      "mfaEnabled": true,
      "mfaRequired": true,
      "passkeyAuthEnabled": true,
      "passwordAuthEnabled": true,
      "passwordPolicy": {
        "minimumLength": 10,
        "minimumStrength": 10,
        "rejectsBreachedPasswords": true,
        "requiresLowercase": true,
        "requiresNumber": true,
        "requiresSymbol": true,
        "requiresUppercase": true
      }
    }
  }
}
```

:::

## Get AuthKit settings

The AuthKit settings for the token's environment.

:::code-group

```graphql language="graphql" title="Query" tab="1"
query AuthkitSettings {
  authkitSettings {
    origin
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "authkitSettings": {
      "origin": "origin_example"
    }
  }
}
```

:::

## Create a password

Set a password for the authenticated user who does not yet have one (e.g. signed up via OAuth). Validates against the environment password policy.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation CreatePassword($input: CreatePasswordInput!) {
  createPassword(input: $input) {
    __typename
    ... on ElevatedAccessTokenExpired {
      message
    }
    ... on ElevatedAccessTokenInvalid {
      message
    }
    ... on PasswordCreated {
      success
    }
    ... on PasswordPolicyViolation {
      code
      message
      violations {
        allowedSymbols
        breachOccurrences
        characterType
        code
        maximumLength
        message
        minimumLength
        strengthSuggestions
        strengthWarning
      }
    }
  }
}
```

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

:::

## Delete a passkey

Remove the specified passkey from the authenticated user's account.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation DeletePasskey($input: DeletePasskeyInput!) {
  deletePasskey(input: $input) {
    __typename
    ... on ElevatedAccessTokenExpired {
      message
    }
    ... on ElevatedAccessTokenInvalid {
      message
    }
    ... on PasskeyDeleted {
      success
    }
  }
}
```

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

:::

## Enroll a TOTP factor

Create a TOTP factor and return the secret and QR URI for the user to scan. This is step 1 of TOTP enrollment.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation EnrollTotp($input: EnrollTotpInput!) {
  enrollTotp(input: $input) {
    __typename
    ... on ElevatedAccessTokenExpired {
      message
    }
    ... on ElevatedAccessTokenInvalid {
      message
    }
    ... on TotpFactor {
      authenticationChallengeId
      authenticationFactorId
      qrCode
      secret
      uri
    }
  }
}
```

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

:::

## List passkeys

List registered passkeys for the authenticated user. Requires a session token.

:::code-group

```graphql language="graphql" title="Query" tab="1"
query Passkeys {
  passkeys {
    createdAt
    id
    lastVerifiedAt
    updatedAt
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "passkeys": [
      {
        "createdAt": "2024-01-01T00:00:00.000Z",
        "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
        "lastVerifiedAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z"
      }
    ]
  }
}
```

:::

## Register a passkey

Begin passkey (WebAuthn) registration for the authenticated user by returning the credential creation options. This is step 1 of the registration ceremony; complete it with `verifyPasskey`.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation RegisterPasskey($input: RegisterPasskeyInput!) {
  registerPasskey(input: $input) {
    __typename
    ... on ElevatedAccessTokenExpired {
      message
    }
    ... on ElevatedAccessTokenInvalid {
      message
    }
    ... on PasskeyRegistrationOptions {
      challengeId
      options
    }
  }
}
```

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

:::

## Remove an MFA factor

Delete all TOTP factors for the authenticated user, effectively resetting MFA.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation RemoveMfaFactor($input: RemoveMfaFactorInput!) {
  removeMfaFactor(input: $input) {
    __typename
    ... on ElevatedAccessTokenExpired {
      message
    }
    ... on ElevatedAccessTokenInvalid {
      message
    }
    ... on MfaFactorRemoved {
      success
    }
  }
}
```

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

:::

## Revoke all sessions

Revokes all active sessions for the authenticated user except the current one.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation RevokeAllSessions {
  revokeAllSessions {
    __typename
    ... on AllSessionsRevoked {
      success
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "revokeAllSessions": {
      "__typename": "AllSessionsRevoked",
      "success": true
    }
  }
}
```

:::

## Revoke a session

Revokes a specific session by ID.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation RevokeSession($input: RevokeSessionInput!) {
  revokeSession(input: $input) {
    __typename
    ... on SessionNotFound {
      sessionId
    }
    ... on SessionRevoked {
      session {
        createdAt
        id
        ipAddress
        isCurrent
        lastActivityAt
        organizationId
        updatedAt
        userAgent
      }
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "revokeSession": {
      "__typename": "SessionNotFound",
      "sessionId": "sessionId_01EHWNCE74X7JSDV0X3SZ3KJNY"
    }
  }
}
```

:::

## List sessions

List active sessions for the authenticated user. Requires a session token.

:::code-group

```graphql language="graphql" title="Query" tab="1"
query Sessions {
  sessions {
    createdAt
    currentLocation {
      cityName
      countryISOCode
    }
    id
    ipAddress
    isCurrent
    lastActivityAt
    organizationId
    state {
      expiresAt
      tag
    }
    updatedAt
    userAgent
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "sessions": [
      {
        "createdAt": "2024-01-01T00:00:00.000Z",
        "currentLocation": {
          "cityName": "cityName_example",
          "countryISOCode": "countryISOCode_example"
        },
        "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
        "ipAddress": "ipAddress_example",
        "isCurrent": true,
        "lastActivityAt": "2024-01-01T00:00:00.000Z",
        "organizationId": "organizationId_example",
        "state": {
          "expiresAt": "2024-01-01T00:00:00.000Z",
          "tag": "tag_example"
        },
        "updatedAt": "2024-01-01T00:00:00.000Z",
        "userAgent": "userAgent_example"
      }
    ]
  }
}
```

:::

## Update a password

Change the password for the authenticated user. Requires the current password for verification and validates the new password against the environment password policy.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation UpdatePassword($input: UpdatePasswordInput!) {
  updatePassword(input: $input) {
    __typename
    ... on PasswordPolicyViolation {
      code
      message
      violations {
        allowedSymbols
        breachOccurrences
        characterType
        code
        maximumLength
        message
        minimumLength
        strengthSuggestions
        strengthWarning
      }
    }
    ... on PasswordUpdated {
      success
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "updatePassword": {
      "__typename": "IncorrectPassword"
    }
  }
}
```

:::

## Verify a passkey

Complete passkey (WebAuthn) registration by verifying the credential created by the authenticator. This is step 2 of the registration ceremony started by `registerPasskey`.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation VerifyPasskey($input: VerifyPasskeyInput!) {
  verifyPasskey(input: $input) {
    __typename
    ... on ElevatedAccessTokenExpired {
      message
    }
    ... on ElevatedAccessTokenInvalid {
      message
    }
    ... on PasskeyVerified {
      success
    }
  }
}
```

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

:::

## Verify a TOTP factor

Confirm TOTP enrollment by verifying a code from the authenticator app. Marks the factor as verified.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation VerifyTotp($input: VerifyTotpInput!) {
  verifyTotp(input: $input) {
    __typename
    ... on ElevatedAccessTokenExpired {
      message
    }
    ... on ElevatedAccessTokenInvalid {
      message
    }
    ... on TotpVerified {
      success
    }
  }
}
```

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

:::

### Query authenticationSettings

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `mfaEnabled` | Boolean! | Whether multi-factor authentication is available in this environment. When `false`, TOTP enrollment should not be offered. |
| `mfaRequired` | Boolean! | Whether multi-factor authentication is mandatory for every user in this environment. |
| `passkeyAuthEnabled` | Boolean! | Whether users may authenticate with a passkey. |
| `passwordAuthEnabled` | Boolean! | Whether users may authenticate with a password. When `false`, `createPassword` and `updatePassword` should not be offered. |
| `passwordPolicy` | PasswordPolicy! | The password requirements configured for the environment. Use these to describe the requirements before a password is submitted; `createPassword` and `updatePassword` enforce them. |

### Query authkitSettings

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `origin` | String! | The HTTPS origin of the preferred AuthKit domain. |

### Mutation createPassword

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `elevatedAccessToken` | String! | Yes | An elevated access token obtained by verifying the current email address. Required to prove recent re-authentication. |
| `password` | String! | Yes | The password to set. Must satisfy the environment password policy. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `ElevatedAccessTokenExpired` | ElevatedAccessTokenExpired | The elevated access token has expired. The user must re-verify their identity. |
| `ElevatedAccessTokenInvalid` | ElevatedAccessTokenInvalid | The elevated access token is invalid. |
| `PasswordCreated` | PasswordCreated | The password was created successfully. |
| `PasswordPolicyViolation` | PasswordPolicyViolation | The provided password does not meet the environment password policy requirements. |
| `UserAlreadyHasPassword` | UserAlreadyHasPassword | The user already has a password set. |

### Mutation deletePasskey

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `elevatedAccessToken` | String! | Yes | An elevated access token obtained by verifying the current email address. Required to prove recent re-authentication. |
| `passkeyId` | ID! | Yes | The ID of the passkey to delete. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `ElevatedAccessTokenExpired` | ElevatedAccessTokenExpired | The elevated access token has expired. The user must re-verify their identity. |
| `ElevatedAccessTokenInvalid` | ElevatedAccessTokenInvalid | The elevated access token is invalid. |
| `PasskeyDeleted` | PasskeyDeleted | The passkey was deleted successfully. |
| `PasskeyNotFound` | PasskeyNotFound | No passkey with the given ID belongs to the authenticated user. |

### Mutation enrollTotp

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `elevatedAccessToken` | String! | Yes | An elevated access token obtained by verifying the current email address. Required to prove recent re-authentication. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `ElevatedAccessTokenExpired` | ElevatedAccessTokenExpired | The elevated access token has expired. The user must re-verify their identity. |
| `ElevatedAccessTokenInvalid` | ElevatedAccessTokenInvalid | The elevated access token is invalid. |
| `TotpAlreadyEnrolled` | TotpAlreadyEnrolled | The user already has a verified TOTP factor enrolled. |
| `TotpFactor` | TotpFactor | TOTP factor details returned after enrollment. |

### Query passkeys

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | DateTime! |  |
| `id` | ID! |  |
| `lastVerifiedAt` | DateTime | When this passkey was last used to authenticate. |
| `updatedAt` | DateTime! |  |

### Mutation registerPasskey

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `elevatedAccessToken` | String! | Yes | An elevated access token obtained by verifying the current email address. Required to prove recent re-authentication. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `ElevatedAccessTokenExpired` | ElevatedAccessTokenExpired | The elevated access token has expired. The user must re-verify their identity. |
| `ElevatedAccessTokenInvalid` | ElevatedAccessTokenInvalid | The elevated access token is invalid. |
| `PasskeyRegistrationOptions` | PasskeyRegistrationOptions | The WebAuthn credential creation options to pass to the browser, plus the challenge ID to send back with the attestation in `verifyPasskey`. |

### Mutation removeMfaFactor

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `elevatedAccessToken` | String! | Yes | An elevated access token obtained by verifying the current email address. Required to prove recent re-authentication. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `ElevatedAccessTokenExpired` | ElevatedAccessTokenExpired | The elevated access token has expired. The user must re-verify their identity. |
| `ElevatedAccessTokenInvalid` | ElevatedAccessTokenInvalid | The elevated access token is invalid. |
| `MfaFactorRemoved` | MfaFactorRemoved | All TOTP factors were removed successfully. |
| `NoMfaFactorsEnrolled` | NoMfaFactorsEnrolled | The user has no TOTP factors to remove. |

### Mutation revokeAllSessions

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `AllSessionsRevoked` | AllSessionsRevoked | All other sessions were revoked successfully. |

### Mutation revokeSession

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `sessionId` | ID! | Yes | The ID of the session to revoke. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `SessionNotFound` | SessionNotFound | No session was found with the given ID. |
| `SessionRevoked` | SessionRevoked | The session was revoked successfully. |

### Query sessions

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | DateTime! |  |
| `currentLocation` | SessionLocation | Approximate geographic location derived from the session IP. |
| `id` | ID! |  |
| `ipAddress` | String |  |
| `isCurrent` | Boolean! | Whether this session is the one making the request. |
| `lastActivityAt` | DateTime |  |
| `organizationId` | String |  |
| `state` | SessionState! | The lifecycle state of a session. |
| `updatedAt` | DateTime! |  |
| `userAgent` | String |  |

### Mutation updatePassword

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `currentPassword` | String! | Yes | The current password for verification. |
| `newPassword` | String! | Yes | The new password. Must satisfy the environment password policy. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `IncorrectPassword` | IncorrectPassword | The provided current password does not match the existing password. |
| `PasswordPolicyViolation` | PasswordPolicyViolation | The provided password does not meet the environment password policy requirements. |
| `PasswordUpdated` | PasswordUpdated | The password was updated successfully. |

### Mutation verifyPasskey

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `challengeId` | String! | Yes | The challenge ID returned by `registerPasskey`. |
| `elevatedAccessToken` | String! | Yes | An elevated access token obtained by verifying the current email address. Required to prove recent re-authentication. |
| `response` | JSON! | Yes | The WebAuthn RegistrationResponseJSON returned by navigator.credentials.create(). |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `ElevatedAccessTokenExpired` | ElevatedAccessTokenExpired | The elevated access token has expired. The user must re-verify their identity. |
| `ElevatedAccessTokenInvalid` | ElevatedAccessTokenInvalid | The elevated access token is invalid. |
| `PasskeyChallengeNotFound` | PasskeyChallengeNotFound | The registration challenge was not found. Challenges are single-use and expire after a few minutes; restart registration. |
| `PasskeyVerificationFailed` | PasskeyVerificationFailed | The WebAuthn attestation response failed verification. |
| `PasskeyVerified` | PasskeyVerified | The passkey was verified and registered successfully. |

### Mutation verifyTotp

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `authenticationChallengeId` | String! | Yes | The authentication challenge ID from enrollTotp. |
| `code` | String! | Yes | The TOTP code from the authenticator app. |
| `elevatedAccessToken` | String! | Yes | An elevated access token obtained by verifying the current email address. Required to prove recent re-authentication. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `ElevatedAccessTokenExpired` | ElevatedAccessTokenExpired | The elevated access token has expired. The user must re-verify their identity. |
| `ElevatedAccessTokenInvalid` | ElevatedAccessTokenInvalid | The elevated access token is invalid. |
| `TotpVerificationFailed` | TotpVerificationFailed | The TOTP verification code was invalid. |
| `TotpVerified` | TotpVerified | The TOTP verification succeeded and the factor is active. |