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

Read more about how Connect integrates with AuthKit here.

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 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"

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:

• Authorization code
• Refresh token
• Client credentials
• Device code

Each is described in greater detail below.

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

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"

Access token

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

{
  "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
}

ID token

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

{
  "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
}

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 -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"

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

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"

Access token

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

{
  "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
}

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 -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"

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

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

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

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

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 https://<subdomain>.authkit.app/.well-known/oauth-authorization-server

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:

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

Read more about CLI Auth here.

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

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 -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'

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

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.

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 -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"
      }
    }
  }'

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 -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" }
        ]
      }
    ]
  }'

The Applications API allows you to programmatically manage Connect Applications and their associated client secrets.

WorkOS Connect supports two types of applications: OAuth and Machine-to-Machine M2M.

OAuth applications are designed for web, mobile, desktop, and CLI applications where a user needs to authenticate.

{
  "object": "connect_application",
  "id": "app_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "client_id": "client_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "name": "My Application",
  "description": "Application description",
  "application_type": "oauth",
  "redirect_uris": [
    {
      "uri": "https://example.com/callback",
      "default": true
    }
  ],
  "uses_pkce": false,
  "is_first_party": true,
  "scopes": ["example-permission:read", "example-permission:write"],
  "created_at": "2024-01-15T12:30:00.000Z",
  "updated_at": "2024-01-15T12:30:00.000Z"
}

M2M applications are designed for server-to-server authentication without user interaction.

{
  "object": "connect_application",
  "id": "app_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "client_id": "client_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "name": "Backend Service",
  "description": "Machine-to-machine application for API access",
  "application_type": "m2m",
  "organization_id": "org_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "scopes": ["api:read", "api:write", "api:admin"],
  "created_at": "2024-01-15T12:30:00.000Z",
  "updated_at": "2024-01-15T12:30:00.000Z"
}

Retrieve details for a specific Connect Application by ID or client ID.

curl https://api.workos.com/connect/applications/app_01J9Q2Z3X4Y5W6V7U8T9S0R1Q \
  --header "Authorization: Bearer sk_example_123456789"

List all Connect Applications in the current environment with optional filtering.

curl "https://api.workos.com/connect/applications?organization_id=org_01J9Q2Z3X4Y5W6V7U8T9S0R1Q&limit=20" \
  --header "Authorization: Bearer sk_example_123456789"

Create a new Connect Application. Supports both OAuth and Machine-to-Machine (M2M) application types.

curl -X POST https://api.workos.com/connect/applications \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "My OAuth App",
    "application_type": "oauth",
    "description": "Customer-facing OAuth application",
    "redirect_uris": [
      {
        "uri": "https://example.com/callback",
        "default": true
      }
    ],
    "uses_pkce": false,
    "is_first_party": false,
    "organization_id": "org_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
    "scopes": ["example-permission:write"]
  }'

Update an existing Connect Application. For OAuth applications, you can update redirect URIs. For all applications, you can update the name, description, and scopes.

curl -X PUT https://api.workos.com/connect/applications/app_01J9Q2Z3X4Y5W6V7U8T9S0R1Q \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Updated Application Name",
    "description": "Updated description",
    "redirect_uris": [
      {
        "uri": "https://example.com/new-callback",
        "default": true
      },
      {
        "uri": "https://example.com/another-callback",
        "default": false
      }
    ],
    "scopes": ["profile", "email", "openid"]
  }'

Delete an existing Connect Application.

curl -X DELETE https://api.workos.com/connect/applications/app_01J9Q2Z3X4Y5W6V7U8T9S0R1Q \
  --header "Authorization: Bearer sk_example_123456789"

Client secrets are used to authenticate Connect Applications when making requests to WorkOS APIs.

When a client secret is first created, the response includes an additional secret field containing the plaintext secret. This is the only time the plaintext secret will be returned.

{
  "object": "connect_application_secret",
  "id": "secret_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "secret": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
  "secret_hint": "abc123",
  "last_used_at": "2024-01-15T14:30:00.000Z",
  "created_at": "2024-01-15T12:30:00.000Z",
  "updated_at": "2024-01-15T14:30:00.000Z"
}

List all client secrets associated with a Connect Application.

The plaintext secret is never returned after creation. Only the secret hint is included.

curl https://api.workos.com/connect/applications/app_01J9Q2Z3X4Y5W6V7U8T9S0R1Q/client_secrets \
  --header "Authorization: Bearer sk_example_123456789"

Create a new client secret for a Connect Application.

This is the only time the plaintext secret will be returned and must be stored securely.

curl -X POST https://api.workos.com/connect/applications/app_01J9Q2Z3X4Y5W6V7U8T9S0R1Q/client_secrets \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  --data '{}'

Delete (revoke) an existing client secret.

curl -X DELETE https://api.workos.com/connect/client_secrets/secret_01J9Q2Z3X4Y5W6V7U8T9S0R1Q \
  --header "Authorization: Bearer sk_example_123456789"