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

# Refresh Token

> Exchange a refresh token for a new access token (JWT) — for Desktop and iOS native clients

Use a long-lived refresh token (30 days) to silently obtain a new short-lived access token (1 hour) without requiring the user to log in again.

### When to Use

* Desktop/iOS native clients whose access token has expired
* Automated token renewal in background before API calls
* Any native client that received a `refreshToken` during login

### Authentication Flow

```mermaid theme={null}
sequenceDiagram
    participant Client as Desktop / iOS
    participant Web as Next.js (Web API)

    Client->>Client: Detect accessToken expired (check JWT exp)
    Client->>Web: POST /api/auth/refresh<br/>{refreshToken}
    Web->>Web: Validate refreshToken hash in DB
    Web->>Web: Sign new JWT with JWKS private key
    Web-->>Client: {accessToken, expiresIn: 3600}
    Client->>Client: Store new accessToken, continue API calls
```

<Note>If the refresh token is expired or invalid, the endpoint returns 401. The client should clear local auth state and redirect to the login screen.</Note>

<ParamField body="refreshToken" type="string" required>
  The refresh token received during login (from `/api/auth/jwt` or device authorization flow)
</ParamField>

<ResponseField name="accessToken" type="string">
  New JWT access token (valid for 1 hour). Usage: `Authorization: Bearer <accessToken>`
</ResponseField>

<ResponseField name="expiresIn" type="number">
  Token validity in seconds: `3600` (1 hour)
</ResponseField>

<RequestExample>
  ```bash Refresh Token theme={null}
  curl --request POST \
    --url https://zeus.agentspro.cn/api/auth/refresh \
    --header 'Content-Type: application/json' \
    --data '{
      "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "accessToken": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Invalid or expired refresh token"
  }
  ```
</ResponseExample>