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

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

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://authkit_domain",
  "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://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
}

`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://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"

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

`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://authkit_domain/oauth2/token \
  -d "client_id=client_01JP8BD0CZ401TDF9X54NT5ZEK" \
  -d "client_secret=1eaaf7a47948398d89e2b07dce912b6a9c0282aa20e88c026fcb42fd6b06b73e" \
  -d "grant_type=client_credentials"

 {
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNzb19vaWRjX2tleV9wYWlyXzAxSlBaWlk3UVA3MTJKMUsyMkI0WlpIMUIzIn0.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJqdGkiOiIwMUpQWlpZN0VCTlA1TjJBTjgxRVlaMkpGUyIsInN1YiI6ImNsaWVudF8wMUpQWlpZN0RYQkNINTcyNUpFQzZYWTZXViIsIm9yZ19pZCI6Im9yZ18wMUpQWlpZN0RNUDM3MlMwRDMzMzY5Wkg2RiIsImV4cCI6MTc0MjY4NjUyMiwiaWF0IjoxNzQyNjgyOTIyfQ.Mi8UdyWT6nRlkamfTmLTca281PtHSh5HO810ly89AaFuVO_zrK1nnLCkI-mGL5GHdBa86eiPoWVhbX-epr4t35VuYfNaBd4LeE3nsjTw1otu51WTCHksiJgMMGprRWB23jATICQyTxffpV4Imk5wbsb3kkBhaHCq3uCgwBEeg73w1lY20DBkAjWEXCwQZOdNw7bFxrVIImH1wZxfPjNhlmrthqzA8kXBC9uul7Io4Yy2fDCT-viDCLBBiRK-uckBMmfwREl7pb296Acthl4xfDJuFDBa9sXPs2ZgEnihNodJYne-ryXFj144-GQ5JX_ungXQSSUEuy-Nf9M5Rru1iQ",
  "expires_in": 3600,
  "token_type": "bearer"
}

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://authkit_domain",
  "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 Continue to the next section

Up next

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

sub: string

org_id?: string

jti: string

exp: DateTime

iat: DateTime

`/oauth2/token`

`Parameters`

`Returns` `object`

`Access token JWT`

`ID token JWT`

`/oauth2/token`

`Parameters`

`Returns` `object`

`/oauth2/token`

`Parameters`

`Returns` `object`

`Access token JWT`