> ## 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.

# 刷新 Token

> 使用 refreshToken 换取新的 accessToken (JWT) — 供桌面端和 iOS 原生客户端使用

使用长期有效的 refreshToken（30 天）静默获取新的短期 accessToken（1 小时），无需用户重新登录。

### 使用场景

* 桌面端/iOS 原生客户端的 accessToken 过期后自动续签
* 后台自动刷新 token，保持 API 调用不中断
* 任何在登录时获得了 `refreshToken` 的原生客户端

### 认证流程

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

    Client->>Client: 检测 accessToken 过期（检查 JWT exp）
    Client->>Web: POST /api/auth/refresh<br/>{refreshToken}
    Web->>Web: 验证 refreshToken 哈希（数据库）
    Web->>Web: 使用 JWKS 私钥签发新 JWT
    Web-->>Client: {accessToken, expiresIn: 3600}
    Client->>Client: 保存新 accessToken，继续 API 调用
```

<Note>如果 refreshToken 过期或无效，端点返回 401。客户端应清除本地认证状态并跳转到登录页。</Note>

<ParamField body="refreshToken" type="string" required>
  登录时获得的 refreshToken（来自 `/api/auth/jwt` 或设备授权流程）
</ParamField>

<ResponseField name="accessToken" type="string">
  新的 JWT accessToken（有效期 1 小时）。使用方式：`Authorization: Bearer <accessToken>`
</ResponseField>

<ResponseField name="expiresIn" type="number">
  Token 有效期（秒）：`3600`（1 小时）
</ResponseField>

<RequestExample>
  ```bash 刷新 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>