WorkOS Connect

WorkOS Connect is a unified interface that simplifies authentication and authorization across customers, partners, and external SaaS tools.

Authorize

When authenticating a user for a WorkOS Connect application, this is the endpoint they should be redirected to. If they’re not already logged in, the user will be redirected to the AuthKit login page. For a third-party application, the user will have to authorize the application’s access on their first access.

cURL

 curl https://<subdomain>.authkit.app/oauth2/authorize -G \
  -d "client_id=client_01JP8BD0CZ401TDF9X54NT5ZEK" \
  -d "nonce=4QWsQj7bUUkCXnoC" \
  --data-urlencode "redirect_uri=https://app.example.com/callback" \
  -d "response_type=code" \
  --data-urlencode "scope=openid profile email offline_access" \
  -d "state=GPc459ttUQhB9oPn"

GET

`/oauth2/authorize`

`Parameters`

`Returns`

Token

This endpoint is called by WorkOS Connect Applications to get access tokens, ID tokens, and refresh tokens, depending on the grant_type provided when requested.

This endpoint is authenticated by providing the WorkOS Application’s client ID and client secret in the body of the request.

There are four grant types available:

Each is described in greater detail below.

Authorization code grant

Used by WorkOS Connect OAuth Applications to exchange an authorization code for access tokens, ID tokens, and refresh tokens.

cURL

 curl -X POST https://<subdomain>.authkit.app/oauth2/token \
  -d "client_id=client_01JP8BD0CZ401TDF9X54NT5ZEK" \
  -d "client_secret=1eaaf7a47948398d89e2b07dce912b6a9c0282aa20e88c026fcb42fd6b06b73e" \
  -d "grant_type=authorization_code" \
  -d "code=01JMGA70GA2W47M7Z53JG355GW" \
  -d "redirect_uri=https://app.example.com/callback"

POST

`/oauth2/token`

`Parameters`

`Returns` `object`

Access token

The access token for WorkOS Connect OAuth Applications contains the following claims.

Decoded access token

JSON

 {
  "iss": "https://<subdomain>.authkit.app",
  "aud": "client_123456789",
  "sub": "user_01JQ0E27VT3MH79RY0FVA4QBP9",
  "org_id": "org_01HRDMC6CM357W30QMHMQ96Q0S",
  "sid": "app_consent_01JQ0E27WE4K1RCMH7Q094M1GJ",
  "jti": "01JQ0E27ZXE4XNHVP870S6PWYN",
  "exp": 1742698034,
  "iat": 1742697734
}

`Access token JWT`

ID token

The ID token, when requested with the openid scope, contains information about the user’s identity, like name and email address.

Decoded ID token

JSON

 {
  "iss": "https://<subdomain>.authkit.app",
  "aud": "client_01JP8BD0CZ401TDF9X54NT5ZEK",
  "sub": "user_01JQ0E27VT3MH79RY0FVA4QBP9",
  "name": "Leroy Jenkins",
  "given_name": "Leroy",
  "family_name": "Jenkins",
  "email": "leroy.jenkins@example.com",
  "email_verified": true,
  "nonce": "f39a8e47d2c9b6fa",
  "exp": 1742702581,
  "iat": 1742698981
}

`ID token JWT`

Refresh token grant

Used by WorkOS Connect OAuth Applications to exchange a refresh token for new access tokens and/or ID tokens. The refresh token is provided when the initial oauth2/authorize request is made with the offline_access scope.

The access token and ID tokens issued here are the same as those issued for the initial authorization_code grant.

cURL

 curl -X POST https://<subdomain>.authkit.app/oauth2/token \
  -d "client_id=client_01JP8BD0CZ401TDF9X54NT5ZEK" \
  -d "client_secret=1eaaf7a47948398d89e2b07dce912b6a9c0282aa20e88c026fcb42fd6b06b73e" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=01JMGA70GA2W47M7Z53JG355GW" \
  -d "scope=openid profile email"

POST

`/oauth2/token`

`Parameters`

`Returns` `object`

Client credentials grant

Used by WorkOS Connect M2M Applications to exchange the app’s credentials for access tokens.

cURL

 curl -X POST https://<subdomain>.authkit.app/oauth2/token \
  -d "client_id=client_01JP8BD0CZ401TDF9X54NT5ZEK" \
  -d "client_secret=1eaaf7a47948398d89e2b07dce912b6a9c0282aa20e88c026fcb42fd6b06b73e" \
  -d "grant_type=client_credentials" \
  -d "scope=openid profile email"

POST

`/oauth2/token`

`Parameters`

`Returns` `object`

Access token

The access token for WorkOS Connect M2M Applications contains the following claims.

Decoded access token

JSON

 {
  "iss": "https://<subdomain>.authkit.app",
  "aud": "client_01K25SZKHKNZZYSP7E5E3N2T0M",
  "sub": "client_01HK20JT00434A411X45ZNPTBA",
  "org_id": "org_01HZ99J6C0H3JBP78CYQM7J0FE",
  "sid": "app_consent_01JQ0E27WE4K1RCMH7Q094M1GJ",
  "jti": "01JQ0E27ZXE4XNHVP870S6PWYN",
  "exp": 1742698034,
  "iat": 1742697734
}

`Access token JWT`

Token introspection

Indicates whether the given token (access token or refresh token) is valid and active. Additionally, it provides details about the token.

This endpoint is authenticated by provided the WorkOS Application’s client ID and client secret in the body of the request.

cURL

 curl -X POST https://<subdomain>.authkit.app/oauth2/introspection \
  -d "client_id=client_01JP8BD0CZ401TDF9X54NT5ZEK" \
  -d "client_secret=1eaaf7a47948398d89e2b07dce912b6a9c0282aa20e88c026fcb42fd6b06b73e" \
  -d "token=eyJhbGciOiJSUzI1NiIsImtpZCI6InNzb19vaWRjX2tleV9wYWlyXzAxSlBYTjZLRjdOQUVBWlRGRFlFU0FFMEtYIn0.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyXzAxSlBYTjZLQTc2MjJLSjRWUDgzWDFOVEtYIiwic2lkIjoiYXBwX2NvbnNlbnRfMDFKUFhONktBUVc4M0FNWFhZNVdYM1JIVEoiLCJqdGkiOiIwMUpQWE42S0ZHWlFZVzNBTTJERVZYODRZUyIsImV4cCI6MTc0MjYwNDg1MywiaWF0IjoxNzQyNjA0NTUzfQ.dsMI3PBp5LWGeUosFUYYLsjC78swFMI4EUVXW1LN7yd80hxLhAvCX6gKN2s9h13a1tkAX77PDI2PooEJ8RQyB-Zcp_wzdomHffjqCeL-YgGojuCUmgjOm9w7kwg86e81tcMBIX3y872pe9jg1HrVs0t_tJNjoLEKtSwm-Flegttyg7M5SikrHKzul0Jv6ovaXjN4RygDPH6Nbg7Ewag5UwYd9aQK7IRG2oXZPC6WjJx-boyRvwgAqJ5pCedRc2ta5-sb3KyrgS6Xb0S3y1KA57RiDvJdQp8z_wL2_4e6iwG00a7OwyorIDpxKl5kAJE_Fct71931lB4EmNsGkVLxoA" \
  -d "token_type_hint=access_token"

POST

`/oauth2/token`

`Parameters`

`Returns` `object`

User information

Provides information about the User referenced by the access token’s sub claim. Which claims are returned depends on the scopes originally granted when the access token was issued.

This endpoint is authenticated by providing the previously acquired access token in the Authorization header.

cURL

 curl -X POST https://<subdomain>.authkit.app/oauth2/userinfo \
  -H "authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6InNzb19vaWRjX2tleV9wYWlyXzAxSlBYTjZLRjdOQUVBWlRGRFlFU0FFMEtYIn0.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyXzAxSlBYTjZLQTc2MjJLSjRWUDgzWDFOVEtYIiwic2lkIjoiYXBwX2NvbnNlbnRfMDFKUFhONktBUVc4M0FNWFhZNVdYM1JIVEoiLCJqdGkiOiIwMUpQWE42S0ZHWlFZVzNBTTJERVZYODRZUyIsImV4cCI6MTc0MjYwNDg1MywiaWF0IjoxNzQyNjA0NTUzfQ.dsMI3PBp5LWGeUosFUYYLsjC78swFMI4EUVXW1LN7yd80hxLhAvCX6gKN2s9h13a1tkAX77PDI2PooEJ8RQyB-Zcp_wzdomHffjqCeL-YgGojuCUmgjOm9w7kwg86e81tcMBIX3y872pe9jg1HrVs0t_tJNjoLEKtSwm-Flegttyg7M5SikrHKzul0Jv6ovaXjN4RygDPH6Nbg7Ewag5UwYd9aQK7IRG2oXZPC6WjJx-boyRvwgAqJ5pCedRc2ta5-sb3KyrgS6Xb0S3y1KA57RiDvJdQp8z_wL2_4e6iwG00a7OwyorIDpxKl5kAJE_Fct71931lB4EmNsGkVLxoA"

POST

`/oauth2/userinfo`

`Returns`

Metadata

Connect exposes several metadata endpoints in order to be compatible with a wide array of clients that support discovery and automatic configuration.

OpenID configuration

This discovery endpoint provides the standard configuration for OpenID clients to interact with WorkOS Connect.

cURL

 curl https://<subdomain>.authkit.app/.well-known/openid-configuration

GET

`/.well-known/openid-configuration`

`Returns` `object`

OAuth Authorization Server

This endpoint provides RFC 6749-compatible OAuth Authorization Server metadata.

Model Context Protocol (MCP) clients that support the latest version of the specification use this endpoint. Read more here about how to use AuthKit as an authorization server for an MCP server.

cURL

 curl https://<subdomain>.authkit.app/.well-known/oauth-authorization-server

GET

`/.well-known/oauth-authorization-server`

`Returns` `object`

CLI Auth

CLI Auth for WorkOS Connect enables third-party applications to build command-line tools that integrate with your app’s credentials using the OAuth 2.0 Device Authorization Flow.

The CLI Auth flow for Connect involves two main endpoints:

The device authorization URL initiates the flow by obtaining device codes, user codes, and verification URIs.
The device access token URL is where the device exchanges the device code for access and refresh tokens after the user authenticates.

Authorize device

Initiates the device authorization flow for WorkOS Connect applications. This endpoint implements the OAuth 2.0 Device Authorization Flow and is designed for CLI applications and other devices with limited input capabilities.

This endpoint is used by third-party applications to authenticate users through WorkOS Connect. Users will be prompted to authorize the application’s access to their data as part of the consent flow.

cURL

 curl -X POST 'https://<subdomain>.authkit.app/oauth2/device_authorization' \
  -d 'client_id=client_01JP8BD0CZ401TDF9X54NT5ZEK' \
  --data-urlencode 'scope=openid profile email'

POST

`/oauth2/device_authorization`

`Parameters`

`Returns`

Device code grant

Exchanges a device code for access and refresh tokens as part of the device authorization flow for WorkOS Connect applications. This endpoint should be polled repeatedly until the user authorizes the request, declines it, or the device code expires.

cURL

 curl -X POST 'https://<subdomain>.authkit.app/oauth2/token' \
  -d 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
  -d 'device_code=ETaHpDNhfxu0HyLhp6b8HGSh26NzYJSKw3TT6aS7HKKBhTyTD0zAW6ApTTolug0b' \
  -d 'client_id=client_01JP8BD0CZ401TDF9X54NT5ZEK'

POST

`/oauth2/token`

`Parameters`

`Returns`

The returned tokens are similar to those provided by the authorization code grant.

Standalone Connect

Standalone Connect allows applications with existing authentication systems to use AuthKit as their OAuth authorization server. Instead of migrating your entire authentication stack, you can leverage WorkOS’s OAuth infrastructure while keeping your existing user authentication as the source of truth.

Read more in the Standalone Connect guide.

Complete external authentication

Completes an external authentication flow and returns control to AuthKit. This endpoint is used with Standalone Connect to bridge your existing authentication system with the Connect OAuth API infrastructure.

After successfully authenticating a user in your application, calling this endpoint will:

Create or update the user in AuthKit, using the given id as its external_id.
Return a redirect_uri your application should redirect to in order for AuthKit to complete the flow

Users are automatically created or updated based on the id and email provided. If a user with the same id exists, their information is updated. Otherwise, a new user is created.

If you provide a new id with an email that already belongs to an existing user, the request will fail with an error as email addresses are unique to a user.

cURL

 curl -X POST https://api.workos.com/authkit/oauth2/complete \
  -H "authorization: Bearer sk_example_123456789" \
  -H "content-type: application/json" \
  -d '{
    "external_auth_id": "ext_auth_01J3X4Y5Z6A7B8C9D0E1F2G3H4",
    "user": {
      "id": "user_12345",
      "email": "leroy.jenkins@example.com",
      "first_name": "Leroy",
      "last_name": "Jenkins",
      "metadata": {
        "department": "Engineering",
        "role": "Developer"
      }
    }
  }'

POST

`/authkit/oauth2/complete`

`Parameters`

`Returns`

The user_consent_options can take an array of consent options that the user will be required to choose from on AuthKit’s OAuth consent screen. The chosen option will then become available as a JWT claim on the issued access token.

These options can be presented as either a flat or grouped set of options.

cURL

 curl -X POST https://api.workos.com/authkit/oauth2/complete \
  -H "authorization: Bearer sk_example_123456789" \
  -H "content-type: application/json" \
  -d '{
    "external_auth_id": "ext_auth_01J3X4Y5Z6A7B8C9D0E1F2G3H4",
    "user": {
      "id": "user_12345",
      "email": "leroy.jenkins@example.com"
    },
    "user_consent_options": [
      {
        "claim": "urn:example:organization",
        "type": "enum",
        "label": "Organization",
        "choices": [
          { "value": "org_123", "label": "Acme Corp" },
          { "value": "org_456", "label": "Globex Inc" }
        ]
      }
    ]
  }'

WorkOS Connect

Authorize

/oauth2/authorize

Parameters

client_id: string

nonce: string

redirect_uri: string

response_type: "code"

scope: string

state?: string

code_challenge?: string

code_challenge_method?: "S256"

Returns

url: string

Token

Authorization code grant

/oauth2/token

Parameters

client_id: string

client_secret: string

grant_type: "authorization_code"

code: string

redirect_uri: string

code_verifier?: string

Returns object

access_token: string

expires_in: integer

id_token: string

refresh_token?: string

token_type: "bearer"

Access token

Access token JWT

iss: string

aud: string

sub: string

org_id?: string

sid: string

jti: string

exp: DateTime

iat: DateTime

ID token

ID token JWT

iss: string

aud: string

sub: string

name?: string

given_name?: string

family_name?: string

email?: string

email_verified?: boolean

exp: DateTime

iat: DateTime

Refresh token grant

/oauth2/token

Parameters

client_id: string

client_secret: string

grant_type: "refresh_token"

refresh_token: string

scope?: string

Returns object

access_token: string

expires_in: integer

id_token: string

refresh_token?: string

token_type: "bearer"

Client credentials grant

/oauth2/token

Parameters

client_id: string

client_secret: string

grant_type: "client_credentials"

scope?: string

Returns object

access_token: string

expires_in: integer

token_type: "bearer"

Access token

Access token JWT

iss: string

`/oauth2/authorize`

`Parameters`

`Returns`

`/oauth2/token`

`Parameters`

`Returns` `object`

`Access token JWT`

`ID token JWT`

`/oauth2/token`

`Parameters`

`Returns` `object`

`/oauth2/token`

`Parameters`

`Returns` `object`

`Access token JWT`

`/oauth2/token`

`Parameters`

`Returns` `object`

`/oauth2/userinfo`

`Returns`

`/.well-known/openid-configuration`

`Returns` `object`

`/.well-known/oauth-authorization-server`

`Returns` `object`

`/oauth2/device_authorization`

`Parameters`

`Returns`