Skip to main content
POST
/
oauth
/
token
/
exchange
Exchange authorization code for access token
curl --request POST \
  --url http://sandbox.mintlify.com/oauth/token/exchange \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "code_abc123...",
  "clientId": "app_abc123...",
  "clientSecret": "cs_abc123...",
  "redirectUri": "https://example.com/oauth/callback",
  "grantType": "authorization_code",
  "codeVerifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}
'
Exchanges an authorization code for access and refresh tokens (Authorization Code Flow).
This is a PUBLIC ENDPOINT (no authentication required). Rate-limited to 15 requests per minute.

​
Request Body

FieldTypeRequiredDescription
codestringYesAuthorization code from /oauth/authorize
clientIdstringYesOAuth application client ID
clientSecretstringYesOAuth application client secret
redirectUristringYesRedirect URI (must match authorization request)
grantTypestringYesGrant type (default: “authorization_code”)

​
Example Request

curl -X POST http://localhost:3001/api/oauth/token/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "code": "code_abc123xyz...",
    "clientId": "app_1234567890abcdef",
    "clientSecret": "cs_1234567890abcdef",
    "redirectUri": "https://example.com/oauth/callback",
    "grantType": "authorization_code"
  }'

​
Example Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "rt_abc123xyz...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:user read:organization"
}

​
Important Notes

  • The redirectUri must exactly match the one used in the authorization request
  • Authorization codes are single-use and expire quickly
  • Store the refresh token securely for token renewal

​
Common Errors

​
400 Bad Request

Invalid request. Check required fields: code, client_id, client_secret, redirect_uri, grant_type.

​
401 Unauthorized

Invalid authorization code, client credentials, or redirect URI mismatch.

​
429 Too Many Requests

Rate limit exceeded. Maximum 15 requests per minute for code exchange.

Body

application/json
​
code
string
required

Authorization code received from the authorization endpoint

Example:

"code_abc123..."

​
clientId
string
required

OAuth application client ID

Example:

"app_abc123..."

​
clientSecret
string
required

OAuth application client secret

Example:

"cs_abc123..."

​
redirectUri
string
required

Redirect URI that was used in the authorization request (must match exactly)

Example:

"https://example.com/oauth/callback"

​
grantType
string
default:authorization_code
required

Grant type (authorization_code for code exchange)

Example:

"authorization_code"

​
codeVerifier
string

PKCE code verifier (required if code_challenge was provided during authorization). Random string used to generate the code_challenge.

Example:

"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

Response

Code exchanged successfully. Returns access_token, refresh_token, token_type (Bearer), expiration time, and scopes.