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:
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://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.
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.
ID token JWT
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.
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 removes that user’s authorization and refresh tokens for the application. See Token and authorization lifetimes for reconnect behavior and the difference between revoking AuthKit sessions and revoking a client’s authorization.
| 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
Used by WorkOS Connect M2M Applications to exchange the app’s credentials for access tokens.
| 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.
Access token JWT
Used by your own first-party WorkOS Connect Applications to exchange an access token issued for one Resource Indicator for an access token issued for another, as described in RFC 8693. 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 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, 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:
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 so the user can consent to it.
| 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" |
| { | |
| "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" | |
| } |
POST/oauth2 /token
Parameters
Returns object
invalid_request: Theresourceparameter is missing, orsubject_token_typeorrequested_token_typehas an unsupported value.invalid_grant: Thesubject_tokenis expired, was not issued by this environment, its consent has been revoked, or its consent is no longer scoped to thesubject_token’s organization.invalid_target: Theresourcedoes not match a configured Resource Indicator.invalid_scope: None of the requested scopes are carried by thesubject_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.