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

# Get API Token

> Obtain a JWT Token using email and password — for external callers to directly access the AI Backend

Obtain a JWT Token directly using email and password, without going through the browser login flow. The token can be used to call any authenticated API on the AI Backend.

### Use Cases

* CLI tools calling the Agent API
* Third-party system integrations
* Postman / cURL debugging
* Automation scripts

### Authentication Flow

```mermaid theme={null}
sequenceDiagram
    participant Client as External Caller
    participant Web as Next.js (Better Auth)
    participant Backend as AI Backend

    Client->>Web: POST /api/auth/api-token<br/>{email, password}
    Web->>Web: Verify credentials + Create Session
    Web->>Web: Issue JWT accessToken + refreshToken
    Web-->>Client: {token, refreshToken, user, expires_in}

    Client->>Backend: POST /api/agent/invoke<br/>Authorization: Bearer <token>
    Backend->>Backend: Verify JWT with JWKS public key
    Backend-->>Client: SSE streaming response

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

<Note>This endpoint is served by the Next.js web layer (not the AI Backend), because JWT issuance relies on Better Auth.</Note>

<ParamField body="email" type="string" required>
  Registered email address
</ParamField>

<ParamField body="password" type="string" required>
  Password
</ParamField>

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

<ResponseField name="refreshToken" type="string">
  Refresh token (valid for 30 days). Use with `POST /api/auth/refresh` to obtain a new access token when it expires.
</ResponseField>

<ResponseField name="user" type="object">
  User information

  <Expandable title="user">
    <ResponseField name="id" type="string">
      User ID (corresponds to `user_id` used for store isolation in the AI Backend)
    </ResponseField>

    <ResponseField name="email" type="string">
      Email address
    </ResponseField>

    <ResponseField name="name" type="string">
      Username
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="expires_in" type="number">
  Access token validity in seconds: `3600` (1 hour)
</ResponseField>

<RequestExample>
  ```bash Get 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 Use Token to Call Agent theme={null}
  # 1. Get 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. Call 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>