Refresh Token

Obtain new access tokens using a valid refresh token. This endpoint allows you to refresh expired access tokens without requiring users to re-authenticate with their credentials.

---

Endpoint

• URL: /api/v1/refresh-token
• Method: POST
• Auth Required: No (uses refresh token)
• Content-Type: application/json

---

Request Structure

Field	Type	Required	Description
refreshToken	string	No	Valid refresh token obtained from sign-in

Example Request:

{
  "refreshToken": "def50200a1b2c3d4e5f6789abcdef..."
}

---

Request Constraints & Business Rules

• A valid refreshToken must be provided.
• Refresh tokens must not be expired or revoked.
• Each refresh token can typically be used multiple times until expiration.
• Refresh tokens are tied to specific user accounts and cannot be transferred.
• Using an invalid or expired refresh token will result in an authentication error.

---

Response Structure

Field	Type	Nullable	Description
accessToken	string	Yes	New JWT access token for API authentication
refreshToken	string	Yes	New or same refresh token for future use
issuedAt	string	No	Token issue timestamp (ISO 8601 format)
expiresAt	string	No	Token expiration timestamp (ISO 8601 format)
expiresIn	integer	No	Token lifetime in seconds

Example Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "def50200a1b2c3d4e5f6789abcdef...",
  "issuedAt": "2024-07-01T11:00:00Z",
  "expiresAt": "2024-07-01T12:00:00Z",
  "expiresIn": 3600
}

---

Error Codes

See Error Codes for details on possible error responses.

---

Security & Validation

• Refresh tokens are validated for authenticity and expiration.
• Each refresh operation may issue a new refresh token (token rotation).
• Refresh tokens have longer lifetimes than access tokens (typically days vs hours).
• Compromised refresh tokens can be revoked server-side.
• Rate limiting prevents abuse of the refresh endpoint.
• All refresh attempts are logged for security monitoring.

---

Token Lifecycle Management

Token Refresh Strategy

1. Proactive Refresh: Refresh tokens before access token expiration
2. Reactive Refresh: Refresh when receiving 401 errors from API calls
3. Token Storage: Update stored tokens with new values after refresh
4. Error Handling: Handle refresh failures by redirecting to sign-in

Best Practices

• Monitor expiresAt timestamp and refresh proactively
• Store both access and refresh tokens securely
• Handle network failures during refresh gracefully
• Implement automatic retry logic with exponential backoff

---

Integration Examples

cURL Example

curl -X POST "https://api.example.com/api/v1/refresh-token" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "def50200a1b2c3d4e5f6789abcdef..."
  }'

JavaScript Example

async function refreshAccessToken() {
  const refreshToken = localStorage.getItem('refreshToken');
  
  try {
    const response = await fetch('/api/v1/refresh-token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        refreshToken: refreshToken
      })
    });

    const result = await response.json();
    if (result.status) {
      // Update stored tokens
      localStorage.setItem('accessToken', result.accessToken);
      localStorage.setItem('refreshToken', result.refreshToken);
      return result.accessToken;
    } else {
      // Refresh failed, redirect to sign-in
      window.location.href = '/sign-in';
    }
  } catch (error) {
    console.error('Token refresh failed:', error);
    window.location.href = '/sign-in';
  }
}

// Automatic token refresh before expiration
function scheduleTokenRefresh(expiresAt) {
  const expirationTime = new Date(expiresAt).getTime();
  const currentTime = Date.now();
  const refreshTime = expirationTime - currentTime - (5 * 60 * 1000); // 5 minutes before expiry
  
  setTimeout(refreshAccessToken, refreshTime);
}

API Interceptor Example

// Axios interceptor for automatic token refresh
axios.interceptors.response.use(
  response => response,
  async error => {
    if (error.response?.status === 401) {
      const newToken = await refreshAccessToken();
      if (newToken) {
        // Retry the original request with new token
        error.config.headers.Authorization = `Bearer ${newToken}`;
        return axios.request(error.config);
      }
    }
    return Promise.reject(error);
  }
);

---

Validation Questions

• How long are refresh tokens valid before expiration?
• Does the system implement refresh token rotation?
• Can refresh tokens be revoked administratively?
• Are there limits on the number of concurrent refresh tokens per user?
• How are refresh token security breaches detected and handled?
• What happens to refresh tokens when users change passwords?
• Are refresh tokens invalidated when users sign out?

---

For integration support, see Contact Support.