Refresh Token

Refresh access token using refresh token

POST /api/auth/refresh

Refresh Token

cURL

curl --request POST \
  --url https://api.example.com/api/auth/refresh \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "refreshToken": "<string>"
}
'

200

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

Show data properties

accessToken · string

New JWT access token for API authentication.

refreshToken · string

New refresh token for future token refreshes.

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