> ## 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.` | 当前窗口内请求过多 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.