Token Refresh Guide

Access tokens have a short lifespan (15 minutes) for security reasons. Refresh tokens (valid for 30 days) allow client applications to renew expired access tokens silently without prompting the user to re-login.

The Refresh Request

POST /api/v2/auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Success Response (`200 OK`)

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.new_token...",
  "expiresIn": 900
}

Client-Side Interceptor Pattern (Dart / Axios)

When making HTTP requests, catch 401 Unauthorized errors, invoke the refresh endpoint once, update the stored access token, and retry the original request.

// Axios Interceptor Example
apiClient.interceptors.response.use(
  (response) => response,
  async (error) => {
    const originalRequest = error.config;
    if (error.response?.status === 401 && !originalRequest._retry) {
      originalRequest._retry = true;
      const refreshToken = await getStoredRefreshToken();
      const res = await axios.post('/api/v2/auth/refresh', { refreshToken });
      const newAccessToken = res.data.accessToken;
      await storeAccessToken(newAccessToken);
      originalRequest.headers['Authorization'] = `Bearer ${newAccessToken}`;
      return apiClient(originalRequest);
    }
    return Promise.reject(error);
  }
);