Authentication

Refresh token

Exchange a refresh token for a new access token without re-authenticating.

The Refresh Token endpoint allows you to exchange a valid refresh token for a new access token. Access tokens typically have a short lifespan, while refresh tokens remain valid longer, enabling continuous authentication without requiring the user to log in again.

Endpoint

POST /v1/auth/refresh

Headers

Key	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer <refresh_token>	Yes

Request Body

{
  "refresh_token": "your_refresh_token_here"
}

Field	Type	Description
refresh_token	string	The refresh token issued during login or token exchange.

Response

Successful Response (200 OK)

{
  "access_token": "new_access_token_value",
  "refresh_token": "new_refresh_token_value",
  "token_type": "Bearer",
  "expires_in": 3600
}

Field	Type	Description
access_token	string	The new access token to be used in subsequent API calls.
refresh_token	string	A new refresh token (optional, depending on implementation).
token_type	string	Always Bearer.
expires_in	int	Lifetime of the access token in seconds (e.g., 3600 = 1 hour).

Error Response (400 / 401 / 403)

{
  "error": "invalid_grant",
  "message": "Refresh token is expired or invalid."
}

Error Code	Meaning
invalid_grant	The refresh token is expired or revoked.
unauthorized	Missing or invalid authorization header.
invalid_request	Required fields are missing or malformed.

Example Usage

cURL

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

JavaScript (Fetch)

const response = await fetch("https://api.example.com/v1/auth/refresh", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer your_refresh_token_here"
  },
  body: JSON.stringify({ refresh_token: "your_refresh_token_here" })
});

const data = await response.json();
console.log(data.access_token);

Info: Always keep refresh tokens secure. If a refresh token is compromised, an attacker could continuously generate new access tokens.

Invalidate session

Need help? Contact Support

Join our Discord Community

Questions? Contact Sales

On this page

Title