Skip to main content
POST
/
oauth
/
token
/
refresh
Refresh OAuth access token
curl --request POST \
  --url http://sandbox.mintlify.com/oauth/token/refresh \
  --header 'Content-Type: application/json' \
  --data '
{
  "refreshToken": "rt_abc123xyz..."
}
'
Exchanges a refresh token for a new access token and refresh token pair. The old refresh token is automatically revoked.
This is a PUBLIC ENDPOINT (no authentication required). Rate-limited to 20 requests per minute.

​
Request Body

FieldTypeRequiredDescription
refreshTokenstringYesRefresh token from token generation

​
Example Request

curl -X POST http://localhost:3001/api/oauth/token/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "rt_abc123xyz..."
  }'

​
Example Response

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

​
Token Rotation

When you refresh a token:
  • Old refresh token is immediately revoked
  • New access token and refresh token are issued
  • Use the new refresh token for future refreshes
  • Old refresh token cannot be reused

​
Best Practices

  • Refresh tokens before they expire
  • Store new refresh tokens securely
  • Handle token refresh errors gracefully
  • Implement automatic token refresh in your client

​
Common Errors

​
400 Bad Request

Invalid request. Refresh token is required.

​
401 Unauthorized

Invalid or expired refresh token. The refresh token may have been used already or has expired.

​
429 Too Many Requests

Rate limit exceeded. Maximum 20 requests per minute for token refresh.

Body

application/json
​
refreshToken
string
required

Refresh token obtained from token generation

Example:

"rt_abc123xyz..."

Response

Token refreshed successfully. Returns new access_token, refresh_token, token_type (Bearer), expiration time, and scopes.