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

# 认证

> 使用 API 密钥对 Topify.ai 公共 API 进行认证。

公共 API 使用 API 密钥认证。每个请求都必须在 `X-API-Key` 请求头中携带您的密钥。

## 请求头

```
X-API-Key: tk_live_<your-key>
```

## 获取 API 密钥

您可以从 Topify.ai 仪表盘的 **Management > Members** 中生成 API 密钥，或通过 [智能体化设置](/api-reference/agentic-setup) 端点以编程方式生成。每个密钥的作用域为您的团队，并可访问该团队拥有的所有项目。仅团队管理员可以创建 API 密钥。

目前不签发项目级作用域的 API 密钥。请将每个 API 密钥视为整个团队的管理员凭证并妥善保管。

<Danger>
  API 密钥仅供受信任的服务端使用。切勿将其嵌入浏览器 JavaScript、移动或桌面客户端代码、公开仓库、日志、AI 提示词或聊天记录。请从密钥管理器或受保护的环境变量加载；一旦泄露，立即轮换。
</Danger>

<Note>
  完整的 API 密钥只会在创建时显示一次。请立即将其保存到密钥管理器。Members 页面仅显示密钥前缀；如果完整值丢失，请创建替代密钥并禁用旧密钥。
</Note>

## 速率限制

请求按 API 密钥进行速率限制。限额取决于您的套餐等级：

| 等级       | 每分钟请求数 | 突发额度 | 每窗口总数 |
| -------- | ------ | ---- | ----- |
| Standard | 60     | 10   | 70    |
| Premium  | 300    | 50   | 350   |

### 响应请求头

每个响应都会包含速率限制信息：

| 请求头                     | 类型      | 描述                     |
| ----------------------- | ------- | ---------------------- |
| `X-RateLimit-Limit`     | integer | 当前窗口内允许的最大请求数          |
| `X-RateLimit-Remaining` | integer | 触发限流前剩余的请求数            |
| `Retry-After`           | integer | 距窗口重置的秒数（仅在 `429` 时返回） |

### 超出速率限制

当您超出限额时，API 会返回 HTTP `429`：

```json theme={null}
{
  "detail": "Rate limit exceeded. Retry after 42 seconds."
}
```

## 密钥生命周期

| 状态           | 行为                 |
| ------------ | ------------------ |
| **Active**   | 密钥有效且接受请求          |
| **Inactive** | 密钥已被管理员禁用，返回 `401` |
| **Expired**  | 密钥已超过过期日期，返回 `401` |

您可以随时从仪表盘停用或删除密钥。

## 示例请求

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "https://topify-customer-api-production.up.railway.app/api/public/v1/projects" \
      -H "X-API-Key: ${TOPIFY_API_KEY}"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import httpx

    client = httpx.Client(
        base_url="https://topify-customer-api-production.up.railway.app/api/public/v1",
        headers={"X-API-Key": os.environ["TOPIFY_API_KEY"]},
    )

    resp = client.get("/projects")
    print(resp.json())
    ```
  </Tab>

  <Tab title="Node.js（服务端）">
    ```javascript theme={null}
    const BASE_URL = "https://topify-customer-api-production.up.railway.app/api/public/v1";
    const API_KEY = process.env.TOPIFY_API_KEY;
    if (!API_KEY) throw new Error("TOPIFY_API_KEY is not set");

    const resp = await fetch(`${BASE_URL}/projects`, {
      headers: { "X-API-Key": API_KEY },
    });
    const data = await resp.json();
    console.log(data);
    ```
  </Tab>
</Tabs>

## 错误响应

| 状态    | 详情                                            | 原因                  |
| ----- | --------------------------------------------- | ------------------- |
| `401` | `Missing X-API-Key header`                    | 未提供 `X-API-Key` 请求头 |
| `401` | `Invalid API key`                             | 无法识别此密钥             |
| `401` | `API key is inactive`                         | 密钥已被管理员禁用           |
| `401` | `API key has expired`                         | 密钥已超过配置的过期日期        |
| `429` | `Rate limit exceeded. Retry after N seconds.` | 当前窗口内请求过多           |