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

# 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 five grant types available:

- [Authorization code](https://workos.com/docs/reference/workos-connect/token/authorization-code-grant)
- [Refresh token](https://workos.com/docs/reference/workos-connect/token/refresh-token-grant)
- [Client credentials](https://workos.com/docs/reference/workos-connect/token/client-credentials-grant)
- [Token exchange](https://workos.com/docs/reference/workos-connect/token/token-exchange-grant)
- [Device code](https://workos.com/docs/reference/workos-connect/cli-auth/device-code-grant)

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.

:::code-group

```bash language="curl" title="Request" tab="1"
curl -X POST https://authkit_domain/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"
```

```json language="json" title="Response" tab="2"
{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNzb19vaWRjX2tleV9wYWlyXzAxSlBYTjZLRjdOQUVBWlRGRFlFU0FFMEtYIn0.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyXzAxSlBYTjZLQTc2MjJLSjRWUDgzWDFOVEtYIiwic2lkIjoiYXBwX2NvbnNlbnRfMDFKUFhONktBUVc4M0FNWFhZNVdYM1JIVEoiLCJqdGkiOiIwMUpQWE42S0ZHWlFZVzNBTTJERVZYODRZUyIsImV4cCI6MTc0MjYwNDg1MywiaWF0IjoxNzQyNjA0NTUzfQ.dsMI3PBp5LWGeUosFUYYLsjC78swFMI4EUVXW1LN7yd80hxLhAvCX6gKN2s9h13a1tkAX77PDI2PooEJ8RQyB-Zcp_wzdomHffjqCeL-YgGojuCUmgjOm9w7kwg86e81tcMBIX3y872pe9jg1HrVs0t_tJNjoLEKtSwm-Flegttyg7M5SikrHKzul0Jv6ovaXjN4RygDPH6Nbg7Ewag5UwYd9aQK7IRG2oXZPC6WjJx-boyRvwgAqJ5pCedRc2ta5-sb3KyrgS6Xb0S3y1KA57RiDvJdQp8z_wL2_4e6iwG00a7OwyorIDpxKl5kAJE_Fct71931lB4EmNsGkVLxoA",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNzb19vaWRjX2tleV9wYWlyXzAxSlBYTjZLRjdOQUVBWlRGRFlFU0FFMEtYIn0.eyJuYW1lIjoiTGVyb3kgSmVua2lucyIsImdpdmVuX25hbWUiOiJMZXJveSIsImZhbWlseV9uYW1lIjoiSmVua2lucyIsImVtYWlsIjoibGVyb3kuamVua2luc0BleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiZXhwIjoxNzQyNjA4MTUzLCJpYXQiOjE3NDI2MDQ1NTN9.UmZj238IIPPtjlc3xEUn_nkNPtw4d71pJLcVyN-0IhDwS1q4bLURIfaV5NdBOUCMmK-BKK5p9NtRUVx5iuTuokah1tQAvfY6dMYNBAD9LMpsv4dvFZMSJHbH9khgrpnLUdvPzTveNBHpmBK7WvZ5VGLlX3Mr-WuI28bvHPI112sNaa-A8gPU7joMgitq01d0raWkBf6XvcAODHD8qKdcS0p4xCnFHVZnfKtgpVDnQJXEFzZnCbcHhdJvaWaTbhLWuWlbIbi4bv-Za3aYAZ-SdcvqkQNWcAPnaj17qLEfY_nyjmiVSW6qkWuq_vJUBLFMmaMbJTYzAsUPAh17_cg24A",
  "refresh_token": "GCOzb87tq7LWpSMaBCjVHnJPH",
  "token_type": "bearer"
}
```

:::

#### Access token

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

:::code-group{title="Decoded access token"}

```json language="json"
{
  "iss": "https://authkit_domain",
  "aud": "client_123456789",
  "client_id": "client_01JP8BD0CZ401TDF9X54NT5ZEK",
  "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.

:::code-group{title="Decoded ID token"}

```json language="json"
{
  "iss": "https://authkit_domain",
  "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
}
```

:::

### Client credentials grant

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

:::code-group

```bash language="curl" title="Request" tab="1"
curl -X POST https://authkit_domain/oauth2/token \
  -d "client_id=client_01JP8BD0CZ401TDF9X54NT5ZEK" \
  -d "client_secret=1eaaf7a47948398d89e2b07dce912b6a9c0282aa20e88c026fcb42fd6b06b73e" \
  -d "grant_type=client_credentials"
```

```json language="json" title="Response" tab="2"
{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNzb19vaWRjX2tleV9wYWlyXzAxSlBaWlk3UVA3MTJKMUsyMkI0WlpIMUIzIn0.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJqdGkiOiIwMUpQWlpZN0VCTlA1TjJBTjgxRVlaMkpGUyIsInN1YiI6ImNsaWVudF8wMUpQWlpZN0RYQkNINTcyNUpFQzZYWTZXViIsIm9yZ19pZCI6Im9yZ18wMUpQWlpZN0RNUDM3MlMwRDMzMzY5Wkg2RiIsImV4cCI6MTc0MjY4NjUyMiwiaWF0IjoxNzQyNjgyOTIyfQ.Mi8UdyWT6nRlkamfTmLTca281PtHSh5HO810ly89AaFuVO_zrK1nnLCkI-mGL5GHdBa86eiPoWVhbX-epr4t35VuYfNaBd4LeE3nsjTw1otu51WTCHksiJgMMGprRWB23jATICQyTxffpV4Imk5wbsb3kkBhaHCq3uCgwBEeg73w1lY20DBkAjWEXCwQZOdNw7bFxrVIImH1wZxfPjNhlmrthqzA8kXBC9uul7Io4Yy2fDCT-viDCLBBiRK-uckBMmfwREl7pb296Acthl4xfDJuFDBa9sXPs2ZgEnihNodJYne-ryXFj144-GQ5JX_ungXQSSUEuy-Nf9M5Rru1iQ",
  "expires_in": 3600,
  "token_type": "bearer"
}
```

:::

#### Access token

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

:::code-group{title="Decoded access token"}

```json language="json"
{
  "iss": "https://authkit_domain",
  "aud": "client_01K25SZKHKNZZYSP7E5E3N2T0M",
  "sub": "client_01HK20JT00434A411X45ZNPTBA",
  "client_id": "client_01HK20JT00434A411X45ZNPTBA",
  "org_id": "org_01HZ99J6C0H3JBP78CYQM7J0FE",
  "jti": "01JQ0E27ZXE4XNHVP870S6PWYN",
  "exp": 1742698034,
  "iat": 1742697734
}
```

:::

### 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](https://workos.com/docs/reference/workos-connect/token/authorization-code-grant/access-token) and [ID tokens](https://workos.com/docs/reference/workos-connect/token/authorization-code-grant/id-token) issued here are the same as those issued for the initial `authorization_code` grant.

The `expires_in` response field describes the access token lifetime, not the refresh token's lifetime. Connect refresh tokens currently have no automatic maximum lifetime or inactivity expiry, and the AuthKit application's maximum session length and inactivity timeout do not apply to them. Their lifetime is independent of the user's AuthKit login session.

By default, public clients rotate refresh tokens on exchange, while confidential clients reuse their refresh token. Always save the latest `refresh_token` returned by a successful refresh, even if its value is unchanged. Rotation happens on use and does not cause an unused token to expire.

[Deleting a user's authorized application](https://workos.com/docs/reference/authkit/user/authorized-application/delete) removes that user's authorization and refresh tokens for the application. See [Token and authorization lifetimes](https://workos.com/docs/authkit/mcp#token-and-authorization-lifetimes) for reconnect behavior and the difference between revoking AuthKit sessions and revoking a client's authorization.

:::code-group

```bash language="curl" title="Request" tab="1"
curl -X POST https://authkit_domain/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"
```

```json language="json" title="Response" tab="2"
{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNzb19vaWRjX2tleV9wYWlyXzAxSlEwMDFSTTROMDAzMjJRWDhYMTJCSFFWIn0.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyXzAxSlEwMDFSRFdaUUdNMEhIMTBZOUJIVlBUIiwic2lkIjoiYXBwX2NvbnNlbnRfMDFKUTAwMVJFM1pBV1g4NDIyWlJQUVY4RVEiLCJqdGkiOiIwMUpRMDAxUk1ZOUNCWkRaU01TUkNDMkc1RCIsImV4cCI6MTc0MjY4MzMzOCwiaWF0IjoxNzQyNjgzMDM4fQ.rCUvi2kpuQmm5hwSinVe_O0SJICY_31QQv4kLNP4nQP_iKrBzb11nBCYaIslJ7nLVIaVQtVZJiu7GSDZ2QAAy3V5LxeICvo52YoB2QMS6LYJz2E7j7jTeWM2yV26Xhg4NHp5ykw6WOG7F9CcoyLbbhbK1NqEs1uYxjlXFONiaQ4FSPl5wk60pXw2E4pzOt-SNpfbWxlJUk3q7pWdajkDmZTGtZdU9hyr1hDTsgJINjd8A7jNpcJeUhT3LQjy5cwhrTaLipQXwrQ0jdfTDnYKxPadrENvKAFGMfQ6BeVAxPKFOIz4loUQuSWt6oHcLpMuH6sEa4eNytW1lT6QdebVDw",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNzb19vaWRjX2tleV9wYWlyXzAxSlEwMDFSTTROMDAzMjJRWDhYMTJCSFFWIn0.eyJuYW1lIjoiQm9iIER5bGFuIiwiZ2l2ZW5fbmFtZSI6IkJvYiIsImZhbWlseV9uYW1lIjoiRHlsYW4iLCJlbWFpbCI6ImJvYkBkeWxhbi5tdXNpYyIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiZXhwIjoxNzQyNjg2NjM4LCJpYXQiOjE3NDI2ODMwMzh9.oTQTWBccCPja8tLEaKqBT63RwydqOMuBFzFXSQcp2CG8EvASEfkoKZCmdhte7dsSm5TVksTo7FwsEYOlNbgn6UAlkYaROFJ-ag6HkRhi6yCrBE_1CC_RNvmxLv_HKbcROG7ELk9pNW7TIfVU92vFxxJ_1xrE69K6gfQpG2F00uMjbEv3wiBtZdPIBWDlLGNj3nSqDT04Raov3hcPlRLYxiz5i6Sb_3nsZf3wgBvbZt0l5R59SgGrC3rXDc_EQ6QgcTVjiuIuMouz8tr3L7DhQCQ0oQF8aeXyLzvKU-Rlnt0DW9eMTs1Al6ZTyQ4WO4A9WqOJL_-i10t_oL6-CIAcXw",
  "refresh_token": "symOF4HwC0Xt3sGAoJSrXlre5",
  "token_type": "bearer"
}
```

:::

### Token exchange grant

Used by your own first-party WorkOS Connect Applications to exchange an access token issued for one [Resource Indicator](https://workos.com/docs/authkit/mcp#configure-mcp-server-url) for an access token issued for another, as described in [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693). For example, an MCP server that receives a token with `aud` of `https://mcp.example.com` can exchange it for a token with `aud` of `https://api.example.com` to call your API as the same user.

The issued [access token](https://workos.com/docs/reference/workos-connect/token/authorization-code-grant/access-token) carries the same `sub`, `sid`, `client_id`, and `org_id` claims as the `subject_token`, and its `aud` claim is the requested `resource`. It expires no later than the `subject_token`, and the request may only narrow its scopes, never widen them. No refresh token or ID token is issued, and the user's consent record is not modified.

The issued access token also carries an `act` (actor) claim, as defined in [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693#section-4.1), whose `sub` is the client ID of the application that performed the exchange. If the `subject_token` already has an `act` claim from an earlier exchange, it is nested as the prior actor, unless the same application is exchanging it again. For example, a token exchanged by one application and then by another carries:

```json
{
  "sub": "user_01HXYZ",
  "client_id": "client_01MCPCLIENT",
  "act": {
    "sub": "client_01SECONDAPP",
    "act": { "sub": "client_01FIRSTAPP" }
  }
}
```

Only first-party Connect Applications authenticating with a client secret can use this grant. Third-party, dynamically registered, and public clients receive an `unauthorized_client` error and must instead request the other resource through the [authorization endpoint](https://workos.com/docs/reference/workos-connect/authorize) so the user can consent to it.

:::code-group

```bash language="curl" title="Request" tab="1"
curl -X POST https://authkit_domain/oauth2/token \
  -d "client_id=client_01JP8BD0CZ401TDF9X54NT5ZEK" \
  -d "client_secret=1eaaf7a47948398d89e2b07dce912b6a9c0282aa20e88c026fcb42fd6b06b73e" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=eyJhbGciOiJSUzI1NiIsImtpZCI6InNzb19vaWRjX2tleV9wYWlyXzAxSlBaWlk3UVA3MTJKMUsyMkI0WlpIMUIzIn0.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJhdWQiOiJodHRwczovL21jcC5leGFtcGxlLmNvbSIsInN1YiI6InVzZXJfMDFKUFpaWTdEWEJDSDU3MjVKRUM2WFk2V1YiLCJzaWQiOiJhcHBsaWNhdGlvbl9jb25zZW50XzAxSlBaWlk3RUJOUDVOMkFOODFFWVoySkZTIiwiY2xpZW50X2lkIjoiY2xpZW50XzAxSlBaWlk3RE1QMzcyUzBEMzMzNjlaSDZGIiwic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBlbWFpbCIsImV4cCI6MTc0MjY4NjUyMiwiaWF0IjoxNzQyNjgyOTIyfQ.signature" \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "resource=https://api.example.com"
```

```json language="json" title="Response" tab="2"
{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNzb19vaWRjX2tleV9wYWlyXzAxSlBaWlk3UVA3MTJKMUsyMkI0WlpIMUIzIn0.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJhdWQiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsInN1YiI6InVzZXJfMDFKUFpaWTdEWEJDSDU3MjVKRUM2WFk2V1YiLCJzaWQiOiJhcHBsaWNhdGlvbl9jb25zZW50XzAxSlBaWlk3RUJOUDVOMkFOODFFWVoySkZTIiwiY2xpZW50X2lkIjoiY2xpZW50XzAxSlBaWlk3RE1QMzcyUzBEMzMzNjlaSDZGIiwic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBlbWFpbCIsImp0aSI6IjAxSlBaWlk3RUJOUDVOMkFOODFFWVoySkZTIiwiZXhwIjoxNzQyNjg2NTIyLCJpYXQiOjE3NDI2ODMyMjJ9.signature",
  "expires_in": 3300,
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "scope": "openid profile email",
  "token_type": "bearer"
}
```

:::

### Error responses

- `invalid_request`: The `resource` parameter is missing, or `subject_token_type` or `requested_token_type` has an unsupported value.
- `invalid_grant`: The `subject_token` is expired, was not issued by this environment, its consent has been revoked, or its consent is no longer scoped to the `subject_token`'s organization.
- `invalid_target`: The `resource` does not match a configured Resource Indicator.
- `invalid_scope`: None of the requested scopes are carried by the `subject_token`.
- `unauthorized_client`: The requesting application is not a first-party Connect Application authenticating with a client secret.
- `unsupported_grant_type`: Token exchange is not enabled for this environment.

### POST /oauth2/token

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | Yes | The client ID of the WorkOS Connect Application. |
| `client_secret` | string | Yes | A secret key associated with the WorkOS Connect Application. |
| `grant_type` | "authorization_code" | Yes | Always `"authorization_code"` for this flow. |
| `code` | string | Yes | The authorization code received from authenticating the user, provided when the user is redirected back to the client. |
| `redirect_uri` | string | Yes | The URL to redirect the user to after they have logged in. This must be the same redirect URI used in the initial `/oauth2/authorize` request. |
| `code_verifier` | string | No | The code verifier used for PKCE (Proof Key for Code Exchange). This is the original random string that was used to generate the `code_challenge` in the authorization request. Required when using PKCE. **Note:** PKCE is only supported by applications created through Dynamic Client Registration, which is required to use MCP (Model Context Protocol) authorization. For setup instructions, see our [MCP guide](/authkit/mcp). |

### POST /oauth2/token

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | Yes | The client ID of the WorkOS Connect Application. |
| `client_secret` | string | Yes | A secret key associated with the WorkOS Connect Application. |
| `grant_type` | "client_credentials" | Yes | Always `"client_credentials"` for this flow. |
| `scope` | string | No | A space-separated set of scopes to use for the access token. |

### POST /oauth2/token

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | Yes | The client ID of the WorkOS Connect Application. |
| `client_secret` | string | Yes | A secret key associated with the WorkOS Connect Application. |
| `grant_type` | "refresh_token" | Yes | Always `"refresh_token"` for this flow. |
| `refresh_token` | string | Yes | The refresh token received from a previous token request. |
| `scope` | string | No | A space-separated set of scopes to use for the tokens to be issued by this request. Must be a subset of the scopes initially specified in the `/oauth2/authorize` request. |

### POST /oauth2/token

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | Yes | The client ID of the WorkOS Connect Application. |
| `client_secret` | string | Yes | A secret key associated with the WorkOS Connect Application. |
| `grant_type` | "urn:ietf:params:oauth:grant-type:token-exchange" | Yes | Always `"urn:ietf:params:oauth:grant-type:token-exchange"` for this flow. |
| `subject_token` | string | Yes | An access token previously issued by this environment through the [authorization code](/reference/workos-connect/token/authorization-code-grant), [refresh token](/reference/workos-connect/token/refresh-token-grant), or token exchange grant. Access tokens issued by the client credentials grant cannot be exchanged. |
| `subject_token_type` | "urn:ietf:params:oauth:token-type:access_token" | Yes | Always `"urn:ietf:params:oauth:token-type:access_token"` for this flow. |
| `resource` | string | Yes | The URI of the resource the new access token is for. Must match one of the [Resource Indicators](/authkit/mcp#configure-mcp-server-url) configured for the environment and becomes the `aud` claim of the issued access token. |
| `requested_token_type` | "urn:ietf:params:oauth:token-type:access_token" | No | The type of token to issue. The only supported value is `"urn:ietf:params:oauth:token-type:access_token"`, which is also the default. |
| `scope` | string | No | A space-separated set of scopes for the issued access token. Scopes not carried by the `subject_token` are dropped; if none remain, the request fails with `invalid_scope`. Defaults to the `subject_token`'s scopes. |