Authentication

Authenticate a user with a specified authentication method.

Authenticate with code

Authenticates a user using AuthKit, OAuth or an organization’s SSO connection.

AuthKit handles all authentication methods, however it is conceptually similar to a social login experience. Like OAuth and SSO, AuthKit returns you a code that you can exchange for an authenticated user. See Integrating with AuthKit.

cURL

 curl --request POST \
  --url https://api.workos.com/user_management/authenticate \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "client_id": "client_123456789",
    "client_secret": "sk_example_123456789",
    "grant_type": "authorization_code",
    "code": "01E2RJ4C05B52KKZ8FSRDAP23J",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
  }
BODY

 {
  "user": {
    "object": "user",
    "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "first_name": "Marcelina",
    "last_name": "Davis",
    "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
    "email": "marcelina.davis@example.com",
    "email_verified": true,
    "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
    "metadata": {
      "timezone": "America/New_York"
    },
    "last_sign_in_at": "2025-06-25T19:07:33.155Z",
    "locale": "en-US",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG",
  "authkit_authorization_code": "authkit_authz_code_abc123",
  "access_token": "eyJhb.nNzb19vaWRjX2tleV9.lc5Uk4yWVk5In0",
  "refresh_token": "yAjhKk123NLIjdrBdGZPf8pLIDvK",
  "impersonator": {
    "email": "admin@foocorp.com",
    "reason": "Investigating an issue with the customer's account."
  },
  "oauth_tokens": {
    "provider": "GoogleOAuth",
    "refresh_token": "1//04g...",
    "access_token": "ya29.a0ARrdaM...",
    "expires_at": 1735141800,
    "scopes": [
      "profile",
      "email",
      "openid"
    ]
  }
}

POST

`/user_management/authenticate`

`Parameters`

`Returns`

Authenticate a user with password

Authenticates a user with email and password.

cURL

 curl --request POST \
  --url https://api.workos.com/user_management/authenticate \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "client_id": "client_123456789",
    "client_secret": "sk_example_123456789",
    "grant_type": "password",
    "email": "marcelina@example.com",
    "password": "i8uv6g34kd490s",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
  }
BODY

 {
  "user": {
    "object": "user",
    "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "first_name": "Marcelina",
    "last_name": "Davis",
    "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
    "email": "marcelina.davis@example.com",
    "email_verified": true,
    "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
    "metadata": {
      "timezone": "America/New_York"
    },
    "last_sign_in_at": "2025-06-25T19:07:33.155Z",
    "locale": "en-US",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG",
  "authkit_authorization_code": "authkit_authz_code_abc123",
  "access_token": "eyJhb.nNzb19vaWRjX2tleV9.lc5Uk4yWVk5In0",
  "refresh_token": "yAjhKk123NLIjdrBdGZPf8pLIDvK",
  "authentication_method": "Password",
  "impersonator": {
    "email": "admin@foocorp.com",
    "reason": "Investigating an issue with the customer's account."
  }
}

POST

`/user_management/authenticate`

`Parameters`

`Returns`

Authenticate with Magic Auth

Authenticates a user by verifying the Magic Auth code sent to the user’s email.

cURL

 curl --request POST \
  --url https://api.workos.com/user_management/authenticate \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "client_id": "client_123456789",
    "client_secret": "sk_example_123456789",
    "grant_type": "urn:workos:oauth:grant-type:magic-auth:code",
    "code": "123456",
    "email": "marcelina.davis@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
  }
BODY

 {
  "user": {
    "object": "user",
    "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "first_name": "Marcelina",
    "last_name": "Davis",
    "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
    "email": "marcelina.davis@example.com",
    "email_verified": true,
    "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
    "metadata": {
      "timezone": "America/New_York"
    },
    "last_sign_in_at": "2025-06-25T19:07:33.155Z",
    "locale": "en-US",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG",
  "authkit_authorization_code": "authkit_authz_code_abc123",
  "access_token": "eyJhb.nNzb19vaWRjX2tleV9.lc5Uk4yWVk5In0",
  "refresh_token": "yAjhKk123NLIjdrBdGZPf8pLIDvK",
  "authentication_method": "MagicAuth",
  "impersonator": {
    "email": "admin@foocorp.com",
    "reason": "Investigating an issue with the customer's account."
  }
}

POST

`/user_management/authenticate`

`Parameters`

`Returns`

Authenticate with refresh token

Use this endpoint to exchange a refresh token for a new access token. Refresh tokens may be rotated after use, so a replacement refresh token is also provided.

cURL

 curl --request POST \
  --url https://api.workos.com/user_management/authenticate \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "client_id": "client_123456789",
    "client_secret": "sk_test_123",
    "grant_type": "refresh_token",
    "refresh_token": "Xw0NsCVXMBf7svAoIoKBmkpEK",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:123.0) Gecko/20100101 Firefox/123.0"
  }
BODY

 {
  "user": {
    "object": "user",
    "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "first_name": "Marcelina",
    "last_name": "Davis",
    "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
    "email": "marcelina.davis@example.com",
    "email_verified": true,
    "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
    "metadata": {
      "timezone": "America/New_York"
    },
    "last_sign_in_at": "2025-06-25T19:07:33.155Z",
    "locale": "en-US",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG",
  "access_token": "eyJhb.nNzb19vaWRjX2tleV9.lc5Uk4yWVk5In0",
  "refresh_token": "yAjhKk123NLIjdrBdGZPf8pLIDvK",
  "impersonator": {
    "email": "admin@foocorp.com",
    "reason": "Investigating an issue with the customer's account."
  }
}

POST

`/user_management/authenticate`

`Parameters`

`Returns`

Authenticate with an email verification code

Authenticates a user with an unverified email and verifies their email address.

A user with an unverified email address won’t be able to authenticate right away. When they attempt to authenticate with their credentials, the API will return an email verification required error that contains a pending authentication token.

If the email setting for email verification is enabled, WorkOS will automatically send a one-time email verification code to the user’s email address. If the email setting is not enabled, retrieve the email verification code to send the email yourself. Use the pending authentication token from the error and the one-time code the user received to authenticate them and to complete the email verification process.

cURL

 curl --request POST \
  --url https://api.workos.com/user_management/authenticate \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "client_id": "client_123456789",
    "client_secret": "sk_example_123456789",
    "grant_type": "urn:workos:oauth:grant-type:email-verification:code",
    "code": "123456",
    "pending_authentication_token": "ql1AJgNoLN1tb9llaQ8jyC2dn",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
  }
BODY

 {
  "user": {
    "object": "user",
    "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "first_name": "Marcelina",
    "last_name": "Davis",
    "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
    "email": "marcelina.davis@example.com",
    "email_verified": true,
    "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
    "metadata": {
      "timezone": "America/New_York"
    },
    "last_sign_in_at": "2025-06-25T19:07:33.155Z",
    "locale": "en-US",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG",
  "authkit_authorization_code": "authkit_authz_code_abc123",
  "access_token": "eyJhb.nNzb19vaWRjX2tleV9.lc5Uk4yWVk5In0",
  "refresh_token": "yAjhKk123NLIjdrBdGZPf8pLIDvK",
  "impersonator": {
    "email": "admin@foocorp.com",
    "reason": "Investigating an issue with the customer's account."
  },
  "oauth_tokens": {
    "provider": "GoogleOAuth",
    "refresh_token": "1//04g...",
    "access_token": "ya29.a0ARrdaM...",
    "expires_at": 1735141800,
    "scopes": [
      "profile",
      "email",
      "openid"
    ]
  }
}

POST

`/user_management/authenticate`

`Parameters`

`Returns`

Authenticate with a time-based one-time password

Authenticates a user enrolled into MFA using time-based one-time password (TOTP).

Users enrolled into MFA are required to enter a TOTP each time they sign in. When they attempt to authenticate with their credentials, the API will return an MFA challenge error that contains a pending authentication token.

To continue with the authentication flow, challenge one of the factors returned by the MFA challenge error response and present a UI to the user to enter the TOTP code. Then, authenticate the user with the TOTP code, the challenge from the factor, and the pending authentication token from the MFA challenge error.

MFA can be enabled via the Authentication page in the WorkOS dashboard.

cURL

 curl --request POST \
  --url https://api.workos.com/user_management/authenticate \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "client_id": "client_123456789",
    "client_secret": "sk_example_123456789",
    "grant_type": "urn:workos:oauth:grant-type:mfa-totp",
    "code": "123456",
    "pending_authentication_token": "ql1AJgNoLN1tb9llaQ8jyC2dn",
    "authenticationChallengeId": "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
  }
BODY

 {
  "user": {
    "object": "user",
    "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "first_name": "Marcelina",
    "last_name": "Davis",
    "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
    "email": "marcelina.davis@example.com",
    "email_verified": true,
    "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
    "metadata": {
      "timezone": "America/New_York"
    },
    "last_sign_in_at": "2025-06-25T19:07:33.155Z",
    "locale": "en-US",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG",
  "authkit_authorization_code": "authkit_authz_code_abc123",
  "access_token": "eyJhb.nNzb19vaWRjX2tleV9.lc5Uk4yWVk5In0",
  "refresh_token": "yAjhKk123NLIjdrBdGZPf8pLIDvK",
  "impersonator": {
    "email": "admin@foocorp.com",
    "reason": "Investigating an issue with the customer's account."
  },
  "oauth_tokens": {
    "provider": "GoogleOAuth",
    "refresh_token": "1//04g...",
    "access_token": "ya29.a0ARrdaM...",
    "expires_at": 1735141800,
    "scopes": [
      "profile",
      "email",
      "openid"
    ]
  }
}

POST

`/user_management/authenticate`

`Parameters`

`Returns`

Authenticate with organization selection

Authenticates a user into an organization they are a member of.

When a user who is a member of multiple organizations attempts to authenticate with their credentials, the API will return an organization selection error that contains a pending authentication token. To continue with the authentication flow, your application should display the list of organizations for the user to choose.

Use the pending authentication token from the error and the organization the user selected in your UI to complete the authentication.

cURL

 curl --request POST \
  --url https://api.workos.com/user_management/authenticate \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "client_id": "client_123456789",
    "client_secret": "sk_example_123456789",
    "grant_type": "urn:workos:oauth:grant-type:organization-selection",
    "pending_authentication_token": "ql1AJgNoLN1tb9llaQ8jyC2dn",
    "organization_id": "org_01H93Z2SYX1D3NJ536M94T8SHP",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
  }
BODY

 {
  "user": {
    "object": "user",
    "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "first_name": "Marcelina",
    "last_name": "Davis",
    "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
    "email": "marcelina.davis@example.com",
    "email_verified": true,
    "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
    "metadata": {
      "timezone": "America/New_York"
    },
    "last_sign_in_at": "2025-06-25T19:07:33.155Z",
    "locale": "en-US",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG",
  "authkit_authorization_code": "authkit_authz_code_abc123",
  "access_token": "eyJhb.nNzb19vaWRjX2tleV9.lc5Uk4yWVk5In0",
  "refresh_token": "yAjhKk123NLIjdrBdGZPf8pLIDvK",
  "impersonator": {
    "email": "admin@foocorp.com",
    "reason": "Investigating an issue with the customer's account."
  },
  "oauth_tokens": {
    "provider": "GoogleOAuth",
    "refresh_token": "1//04g...",
    "access_token": "ya29.a0ARrdaM...",
    "expires_at": 1735141800,
    "scopes": [
      "profile",
      "email",
      "openid"
    ]
  }
}

POST

`/user_management/authenticate`

`Parameters`

`Returns`

Authenticates a user using an AuthKit session cookie. This method does not make a network call, but simply unseals an existing session cookie and decodes the JWT claims from the access token.

JavaScript

 import {
  AuthenticateWithSessionCookieFailureReason,
  WorkOS,
} from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789', {
  // clientId is required to be passed in to use the authenticateWithSessionCookie method
  clientId: 'client_123456789',
});

const { authenticated, ...restOfAuthenticationResponse } =
  await workos.userManagement.authenticateWithSessionCookie({
    sessionData: 'sealed_session_cookie_data',
    cookiePassword: 'password_previously_used_to_seal_session_cookie',
  });

if (authenticated) {
  // User is authenticated and session data can be utilized
  const { sessionId, organizationId, role, permissions } =
    restOfAuthenticationResponse;
} else {
  const { reason } = restOfAuthenticationResponse;

  // Can use AuthenticateWithSessionCookieFailureReason to handle failure reasons
  if (
    reason ===
    AuthenticateWithSessionCookieFailureReason.NO_SESSION_COOKIE_PROVIDED
  ) {
    // Redirect the user to the login page
  }
}

 {
  "authenticated": true,
  "session_id": "session_01HQSXZGF8FHF7A9ZZFCW4387R",
  "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG",
  "role": "member",
  "roles": ["member"],
  "permissions": ["posts:read", "posts:write"]
}

 {
  "authenticated": false,
  "reason": "invalid_session_cookie"
}

`userManagement.authenticateWithSessionCookie()`

`Parameters` `object`

`Returns` `object`

Refresh and seal session data

Unseals the provided session data from a user’s session cookie, authenticates with the existing refresh token, and returns the sealed data for the refreshed session.

JavaScript

 import {
  RefreshAndSealSessionDataFailureReason,
  WorkOS,
} from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789', {
  // clientId is required to be passed in to use the refreshAndSealSessionData method
  clientId: 'client_123456789',
});

const { authenticated, ...restOfRefreshResponse } =
  await workos.userManagement.refreshAndSealSessionData({
    sessionData: 'sealed_session_cookie_data',
    cookiePassword: 'password_previously_used_to_seal_session_cookie',
  });

if (authenticated) {
  const { sealedSession } = restOfRefreshResponse;

  // Set the sealed session in a cookie
} else {
  const { reason } = restOfRefreshResponse;

  // Can use RefreshAndSealSessionDataFailureReason to handle failure reasons
  if (
    reason === RefreshAndSealSessionDataFailureReason.NO_SESSION_COOKIE_PROVIDED
  ) {
    // Redirect the user to the login page
  }
}

 {
  "authenticated": true,
  "sealed_session": "Fe26.2*1*d7f59d8b9d29c26c44dd3df2b56a7d1d40d4"
}

 {
  "authenticated": false,
  "reason": "invalid_session_cookie"
}

`userManagement.refreshAndSealSessionData()`

`Parameters` `object`

`Returns` `object`

Get authorization URL Continue to the next section

Up next

Authentication

Authenticate with code

/user_management/authenticate

Parameters

client_id: string

client_secret?: string

code_verifier?: string

grant_type: "authorization_code"

code: string

invitation_token?: string

ip_address?: string

user_agent?: string

device_id?: string

Returns

user: object

organization_id?: string

authkit_authorization_code?: string

access_token: string

refresh_token: string

impersonator?: object

oauth_tokens?: object

Authenticate a user with password

/user_management/authenticate

Parameters

client_id: string

client_secret: string

grant_type: "password"

email: string

password: string

invitation_token?: string

ip_address?: string

user_agent?: string

device_id?: string

Returns

user: object

organization_id?: string

authkit_authorization_code?: string

access_token: string

refresh_token: string

authentication_method?: "Password"

impersonator?: object

Authenticate with Magic Auth

/user_management/authenticate

Parameters

client_id: string

client_secret: string

grant_type: "urn:workos:oauth:grant-type:magic-auth:code"

code: string

invitation_token?: string

email: string

ip_address?: string

user_agent?: string

device_id?: string

Returns

user: object

organization_id?: string

authkit_authorization_code?: string

access_token: string

refresh_token: string

authentication_method?: "MagicAuth"

impersonator?: object

Authenticate with refresh token

/user_management/authenticate

Parameters

client_id: string

client_secret: string

grant_type: "refresh_token"

refresh_token: string

organization_id?: string

ip_address?: string

user_agent?: string

device_id?: string

Returns

user: object

organization_id?: string

access_token: string

refresh_token: string

impersonator?: object

Authenticate with an email verification code

/user_management/authenticate

`/user_management/authenticate`

`Parameters`

`Returns`

`/user_management/authenticate`

`Parameters`

`Returns`

`/user_management/authenticate`

`Parameters`

`Returns`

`/user_management/authenticate`

`Parameters`

`Returns`

`/user_management/authenticate`

`Parameters`

`Returns`

`/user_management/authenticate`

`Parameters`

`Returns`

`/user_management/authenticate`

`Parameters`

`Returns`

`userManagement.authenticateWithSessionCookie()`

`Parameters` `object`

`Returns` `object`