Skip to main content
POST
/
api
/
auth
/
refresh
Refresh Token
curl --request POST \
  --url https://api.example.com/api/auth/refresh \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "refreshToken": "<string>"
}
'
{
  "success": true,
  "data": {
    "accessToken": "<string>",
    "refreshToken": "<string>"
  }
}
Obtains a new access token and refresh token pair using a valid refresh token. Requires the existing access token (even if expired) in the Authorization header to identify the user. The old refresh token is automatically revoked.

​
Authentication

​
Authorization
string
required
Bearer token with the current access token (can be expired). Used to decode the user ID.Format: Bearer <access_token>

​
Request Body

​
refreshToken
string
required
Valid refresh token previously issued during login or registration.

​
Response

​
success
boolean
Indicates if the request was successful.
​
data
object
Contains the new token pair.

​
Error Responses

​
401 Unauthorized
Invalid or expired refresh token, missing access token, or user not found/disabled.
{
  "success": false,
  "error": {
    "message": "Invalid refresh token",
    "statusCode": 401
  }
}

{
  "success": false,
  "error": {
    "message": "Missing or unreadable access token",
    "statusCode": 401
  }
}

{
  "success": false,
  "error": {
    "message": "User not found or disabled",
    "statusCode": 401
  }
}
​
400 Bad Request
Invalid request body or validation error.
{
  "success": false,
  "error": {
    "message": "Validation error",
    "statusCode": 400,
    "details": []
  }
}

​
Example Request

curl -X POST https://api.example.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "refreshToken": "rt_clx1234567890abcdef"
  }'

​
Example Response

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "rt_clx9876543210zyxwvu"
  }
}

​
Notes

  • Both the access token (in Authorization header) and refresh token (in body) are required
  • The access token is decoded to extract the user ID, but doesn’t need to be valid/unexpired
  • The old refresh token is revoked and a new pair is issued
  • This implements token rotation for enhanced security

Build docs developers (and LLMs) love

Get started for freeTalk to us