Refresh Token

Refreshes the access token using a valid refresh token. Returns new JWT access and refresh tokens.

Endpoint

POST /auth/refresh-token

Authentication: Tenant authentication required

Description

The refresh-token endpoint allows users to obtain new access and refresh tokens using a valid refresh token. This is useful when the access token has expired and needs to be renewed without requiring the user to sign in again.

After successful token refresh:

• New JWT access and refresh tokens are generated and returned
• The old refresh token remains valid until it expires
• The user can continue using the API with the new access token

Request

Body

{
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Parameter	Type	Required	Description	Constraints
refreshToken	string	Yes	JWT refresh token	Valid JWT format

Response

Status Code: 201 Created

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "accessTokenExpireAt": "2025-01-15T11:30:00.000Z",
    "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshTokenExpireAt": "2025-01-16T10:30:00.000Z",
    "userId": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
  }
}

Field	Type	Description
accessToken	string	JWT access token
accessTokenExpireAt	string	Access token expiration timestamp
refreshToken	string	JWT refresh token
refreshTokenExpireAt	string	Refresh token expiration timestamp
userId	string	ULID user identifier

Rate Limiting

Rate limiting is applied to prevent abuse and ensure system stability. The refresh-token endpoint has the following rate limits:

Limit Type	Rate	Window
Per IP	20 requests	1 hour

When rate limits are exceeded, the API returns a 429 Too Many Requests status code.

For information about rate limit headers, see Rate Limiting in the overview.

Errors

For detailed explanations of all error codes, see the Error Codes page where you can find all system errors.

400 Bad Request - Validation Error

Occurs when the request body fails validation. Common causes include invalid JWT format or missing refresh token.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "The provided request data is invalid.",
    "code": "VALIDATION_ERROR",
    "status": 400,
    "validation": {
      "refreshToken": "Invalid JWT format"
    }
  }
}

Field	Error Message	Cause
refreshToken	Invalid JWT format	Token is not a valid JWT
refreshToken	Required	Refresh token is missing

401 Unauthorized - Invalid Refresh Token

Occurs when the refresh token is invalid, expired, or cannot be decoded.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Invalid refresh token",
    "code": "INVALID_REFRESH_TOKEN",
    "status": 401
  }
}

429 Too Many Requests - Rate Limit Exceeded

Occurs when the rate limit is exceeded. See Rate Limiting section for details.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Too many requests",
    "code": "TOO_MANY_REQUESTS",
    "status": 429
  }
}

500 Internal Server Error

Occurs when an internal error happens during token refresh. Common causes include missing decoded refresh token or other unexpected system state.

Error codes:

• UNEXPECTED_STATE - Unexpected system state (e.g., missing decoded refresh token)
• INTERNAL_SERVER - General internal server error

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Missing decoded refresh token",
    "code": "UNEXPECTED_STATE",
    "status": 500
  }
}

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Something went wrong on our side.",
    "code": "INTERNAL_SERVER",
    "status": 500
  }
}

Notes

• New tokens are generated with the same authentication method as the original refresh token
• Store refresh tokens securely and refresh access tokens before they expire to prevent unnecessary API requests
• If both the access token and refresh token have expired, the user should be considered force logged out and must sign in again