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

# 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:

- [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)
- [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.

#### Request

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

#### Response

```json
{
  "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.

#### Decoded access token

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

#### Decoded ID token

```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.

#### Request

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

#### Response

```json
{
  "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.

#### Decoded access token

```json
{
  "iss": "https://authkit_domain",
  "aud": "client_01K25SZKHKNZZYSP7E5E3N2T0M",
  "sub": "client_01HK20JT00434A411X45ZNPTBA",
  "org_id": "org_01HZ99J6C0H3JBP78CYQM7J0FE",
  "sid": "app_consent_01JQ0E27WE4K1RCMH7Q094M1GJ",
  "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.

#### Request

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

#### Response

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

### 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. |