Token Refresh

Refresh the access token using a refresh token.

Endpoint

POST /api/v3/auth/token/refresh

Description

Obtains a new access token using a valid refresh token. Use this endpoint when the access token has expired or is about to expire.

Authentication

This endpoint does not require Bearer token authentication. The refresh token is provided in the request body.

Request Body

Field	Type	Required	Description
refreshToken	string	Yes	Valid refresh token from login or previous refresh

Response

Returns new session data with fresh tokens.

Field	Type	Description
accessToken	string	New JWT access token
refreshToken	string	New refresh token
tokenType	string	Token type (bearer)
expiresIn	integer	Token lifetime in seconds
expiresAt	integer	Token expiration timestamp
user	object	User information

Usage

import requests

response = requests.post(
    "https://cadenza-api-uat.algo724.com/api/v3/auth/token/refresh",
    json={
        "refreshToken": "v1.MjAyNC0wMS0xNVQxMDowMDowMFo..."
    }
)

data = response.json()["data"]
new_access_token = data["accessToken"]
new_refresh_token = data["refreshToken"]  # Update stored refresh token

curl -X POST https://cadenza-api-uat.algo724.com/api/v3/auth/token/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "v1.MjAyNC0wMS0xNVQxMDowMDowMFo..."}'

Example Response

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "v1.new-refresh-token-here...",
    "tokenType": "bearer",
    "expiresIn": 3600,
    "expiresAt": 1703059835,
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  },
  "success": true,
  "errno": 0,
  "error": null
}

Error Responses

HTTP Code	Error	Description
400	Invalid request	Missing refresh token
401	Invalid token	Refresh token is invalid or expired

Example Error

{
  "data": null,
  "success": false,
  "errno": -100003,
  "error": "Invalid refresh token"
}

Token Refresh Strategy

Implement proactive token refresh in your application:

import time

class TokenManager:
    def __init__(self, access_token: str, refresh_token: str, expires_at: int):
        self.access_token = access_token
        self.refresh_token = refresh_token
        self.expires_at = expires_at

    def get_valid_token(self) -> str:
        # Refresh 5 minutes before expiry
        if time.time() > self.expires_at - 300:
            self._refresh()
        return self.access_token

    def _refresh(self):
        response = requests.post(
            "https://cadenza-api-uat.algo724.com/api/v3/auth/token/refresh",
            json={"refreshToken": self.refresh_token}
        )
        data = response.json()["data"]
        self.access_token = data["accessToken"]
        self.refresh_token = data["refreshToken"]
        self.expires_at = data["expiresAt"]

Notes

• The refresh token is also updated on each refresh - always store the new refresh token
• Refresh tokens have a longer lifetime than access tokens
• If the refresh token expires, the user must log in again
• Implement automatic refresh before the access token expires for seamless user experience