# API Keys

API keys 允许您的服务器与 DailyPlay API 进行身份验证。密钥从面板创建，并在进行 API 调用时用于 `x-api-key` 头。

:::note[需要 Business 层级]
API keys 仅适用于 **Business 层级**或更高的组织。
:::

## 创建 API Key

1. 登录 DailyPlay 面板
2. 在侧边栏导航到 **Connect → API Keys**
3. 点击 **Create API Key**
4. 输入名称（例如「Production CRM」）与可选描述
5. （可选）若密钥将为 AI 智能体提供支持，启用 **MCP scopes**（见下方）
6. （可选）设置过期日期
7. 点击 **Create**

:::caution
立即复制生成的密钥 — 它只显示一次，之后无法再次检索。
:::
密钥格式为 `dpk_<40 hex characters>`，例如：

```
dpk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
```

## 密钥范围限定

API keys 可限定范围以限制其可访问的资源：

| 范围 | 说明 |
| ----------------------- | ----------------------------------------------------------------- |
| **All games & streams** | 默认 — 密钥可为组织中的任何资源创建会话 |
| **Specific games** | 限制为游戏 ID 列表 |
| **Specific streams** | 限制为 stream ID 列表 |

尝试为密钥范围外的资源创建会话会返回 `403 Forbidden` 错误。

## MCP Scopes

除游戏/stream 白名单外，密钥还可携带授予远程 [MCP 服务器](/zh/api/mcp/) 访问权限的 **MCP scopes**。范围默认为拒绝：

| 范围 | 授予 |
| --- | --- |
| _(none)_ | 仅会话令牌生成（旧版 / REST 行为） |
| `mcp:templates:read` | 列出并检查模板 |
| `mcp:games:read` / `mcp:games:write` | 读取或创建/更新游戏与奖品 |
| `mcp:streams:read` / `mcp:streams:write` | 读取或创建/更新 streams |
| `mcp:connections:read` / `mcp:connections:write` | 管理组织集成 |
| `mcp:analytics_providers:read` / `mcp:analytics_providers:write` | 管理客户端分析提供商 |
| `mcp:gallery:read` / `mcp:gallery:write` | 列出图库媒体或删除未使用素材 |
| `mcp:vouchers:read` / `mcp:vouchers:write` | 读取或管理兑换码集与代码 |
| `mcp:reports:read` | 阅读组织分析与报告 |
| `mcp:ai` | 品牌提取、漏斗向导、图片生成 |
| `mcp:sessions:write` | 通过 MCP 生成游玩会话 |

您可稍后从 API Keys 列表编辑 MCP scopes，而无需轮换密钥。完整工具列表见 [MCP Tools](/zh/api/mcp-tools/)。

## 速率限制

每个 API key 具有可配置的速率限制：

| 限制 | 默认 | 说明 |
| ---------- | ------- | --------------------------- |
| Per minute | 60 | 每分钟最大请求数 |
| Per day | 10,000 | 每天最大请求数 |

超过速率限制时，API 返回 `429 Too Many Requests` 响应。

## 撤销密钥

您可随时从面板撤销 API key：

1. 前往 **Connect → API Keys**
2. 在列表中找到密钥（通过其 `dpk_****` 前缀与名称识别）
3. 点击撤销操作

撤销密钥：

- 立即阻止使用该密钥的所有未来 API 调用
- **不会**使已用该密钥创建的 session tokens 失效
- 保留审计追踪 — 密钥记录保留但标记为无效
- 如需可重新激活

## 安全

- 密钥在存储前以 **SHA-256 哈希** — 无法从数据库恢复原始密钥
- 仅前 8 个字符（`dpk_xxxx`）以明文存储用于识别
- 密钥可设置为在特定日期**自动过期**
- 所有密钥使用情况均记录用于审计

## 通过 API 管理密钥

您也可以使用已认证请求（Clerk bearer token）以编程方式管理 API keys：

| 方法 | 端点 | 说明 |
| -------- | --------------------------------------- | ----------------------------- |
| `GET` | `/api/org-api-keys?org_id=<id>` | 列出组织的所有 API keys |
| `POST` | `/api/org-api-keys` | 创建新 API key |
| `PATCH` | `/api/org-api-keys` | 更新或撤销 API key |
| `DELETE` | `/api/org-api-keys?id=<id>&org_id=<id>` | 永久删除 API key |

### 创建密钥（API）

```bash
curl -X POST https://app.dailyplay.ai/api/org-api-keys \
  -H "Authorization: Bearer <clerk_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": 1,
    "name": "Production CRM",
    "description": "Used by the CRM to issue game links",
    "allowed_game_ids": [42, 43],
    "rate_limit_per_minute": 60,
    "rate_limit_per_day": 10000,
    "expires_at": "2027-01-01T00:00:00Z"
  }'
```

响应包含原始密钥（仅显示一次）：

```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Production CRM",
    "key_prefix": "dpk_a1b2",
    "key": "dpk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}
```