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

# 获取 API Token

> 用邮箱密码获取 JWT Token — 供外部调用者直接访问 AI Backend

用邮箱密码直接获取 JWT Token，无需走浏览器登录流程。获取的 Token 可以用于直接调用 AI Backend 所有需要认证的 API。

### 使用场景

* CLI 工具调用 Agent API
* 第三方系统集成
* Postman / cURL 调试
* 自动化脚本

### 认证流程

```mermaid theme={null}
sequenceDiagram
    participant Client as 外部调用者
    participant Web as Next.js (Better Auth)
    participant Backend as AI Backend

    Client->>Web: POST /api/auth/api-token<br/>{email, password}
    Web->>Web: 验证凭据 + 创建 Session
    Web->>Web: 签发 JWT accessToken + refreshToken
    Web-->>Client: {token, refreshToken, user, expires_in}

    Client->>Backend: POST /api/agent/invoke<br/>Authorization: Bearer <token>
    Backend->>Backend: JWKS 公钥验证 JWT
    Backend-->>Client: SSE 流式响应

    Note over Client,Web: accessToken 过期后
    Client->>Web: POST /api/auth/refresh<br/>{refreshToken}
    Web-->>Client: {accessToken, expiresIn}
```

<Note>此接口由 Next.js Web 端提供（不是 AI Backend），因为 JWT 签发依赖 Better Auth。</Note>

<ParamField body="email" type="string" required>
  注册邮箱
</ParamField>

<ParamField body="password" type="string" required>
  密码
</ParamField>

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

<ResponseField name="refreshToken" type="string">
  Refresh Token（有效期 30 天）。accessToken 过期后，使用 `POST /api/auth/refresh` 获取新的 accessToken。
</ResponseField>

<ResponseField name="user" type="object">
  用户信息

  <Expandable title="user">
    <ResponseField name="id" type="string">
      用户 ID（即 AI Backend 中用于 Store 隔离的 `user_id`）
    </ResponseField>

    <ResponseField name="email" type="string">
      邮箱
    </ResponseField>

    <ResponseField name="name" type="string">
      用户名
    </ResponseField>
  </Expandable>
</ResponseField>

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

<RequestExample>
  ```bash 获取 Token theme={null}
  curl --request POST \
    --url https://zeus.agentspro.cn/api/auth/api-token \
    --header 'Content-Type: application/json' \
    --data '{
      "email": "user@example.com",
      "password": "your-password"
    }'
  ```

  ```bash 使用 Token 调用 Agent theme={null}
  # 1. 获取 token
  TOKEN=$(curl -s -X POST https://zeus.agentspro.cn/api/auth/api-token \
    -H 'Content-Type: application/json' \
    -d '{"email":"user@example.com","password":"xxx"}' | jq -r '.token')

  # 2. 调用 Agent
  curl -X POST https://zeus-api.agentspro.cn/api/agent/invoke \
    -H "Authorization: Bearer $TOKEN" \
    -H 'Content-Type: application/json' \
    -d '{
      "message": "Hello",
      "llm_config": {
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "sk-...",
        "modelName": "gpt-4o"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6Inh4eCJ9...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
    "user": {
      "id": "user_abc123",
      "email": "user@example.com",
      "name": "Frank"
    },
    "expires_in": 3600
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Invalid email or password"
  }
  ```
</ResponseExample>