> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learnway.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Refresh Guide

> Handling JWT expiration, silent refresh patterns, and token renewal in client applications.

# 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

```http theme={null}
POST /api/v2/auth/refresh
Content-Type: application/json

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

### Success Response (`200 OK`)

```json theme={null}
{
  "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.

```typescript theme={null}
// 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);
  }
);
```