---
title: API 密钥
description: 创建完全访问或仅发送权限的 API 密钥，把密钥限定到某个域名或收件箱，并管理这些密钥。
ai:
  exclude: true
---

API 密钥是你的代码在每次请求中携带的凭据。在控制台的 **API 密钥**下创建，也可以通过 API 本身创建。密钥只在创建时显示一次，请保存到你的密钥管理工具里。

```sh
curl https://api.billionsend.com/emails \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@example.com",
    "to": "success@simulator.amazonses.com",
    "subject": "Hi",
    "text": "Hello."
  }'
```

密钥以 `bs_` 开头。BillionSend 只保存密钥的哈希值，所以丢失的密钥无法再次显示：请吊销它，再创建一个新的。

## 创建密钥

在控制台打开 **API 密钥**，选择**创建 API 密钥**。所有者、管理员和开发者都可以创建，见[团队角色](/docs/zh-hans/team-roles)。需要选择：

- **名称**：1 到 80 个字符，用来区分不同的密钥。之后可以重命名。
- **权限**：**完全访问**或**仅发送**。
- **域名**：**任意域名**，或你团队的某一个已验证域名。
- **限定到某个收件箱**（有收件箱之后才会显示）：密钥所限定的那一个[收件箱](/docs/zh-hans/inboxes)。

通过 API 创建：

```sh
curl -X POST "https://api.billionsend.com/api-keys" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "permission": "sending_access",
    "domain_id": "af8ad875-319f-4df5-a359-4f2430f3e766"
  }'
```

返回值是 `{ "id": "…", "token": "bs_…" }`：令牌只在这里出现一次。`GET /api-keys` 列出有效的密钥（不含令牌），`DELETE /api-keys/{id}` 立即吊销一个密钥，使用它的请求会马上失败。

## 权限

| 权限 | 可以做什么 |
| --- | --- |
| **完全访问** | 使用所有端点：发送、联系人、分群、订阅主题、群发、域名、Webhook、模板、收到的邮件和 API 密钥。[限定到某个域名](#把密钥限定到某个域名)的密钥只能访问其中一部分。 |
| **仅发送** | 只能发送邮件（`POST /emails`、`POST /emails/batch`），其他什么都不能做。发送之外的所有操作，以及对已存储邮件的所有读取，都会返回 `403 restricted_api_key`。 |

在发送事务邮件的应用里使用仅发送密钥。即使仅发送密钥泄露，也无法读取你的联系人、修改你的域名或创建其他密钥。

## 把密钥限定到某个域名

限定到某个域名的密钥只在这一个域名内工作，访问不到任何属于整个团队的内容。域名必须先通过验证，才能把密钥限定到它；共享收件箱子域名不能使用。

| 范围 | 密钥能做什么 |
| --- | --- |
| 发送、邮件、收到的邮件、收件箱、退订、群发 | 只限该域名的。请求其他域名会返回 `403 restricted_api_key`。 |
| `GET /emails/metrics` | 只能读取该域名的数据；在 `domain_id` 里指定其他域名会返回 `403 restricted_api_key`。 |
| `GET /domains` 和 `/domains/{id}`（读取、修改、删除、验证） | 只能列出并操作它自己的域名。其他任何域名（包括共享子域名）都会返回 `404`。 |
| `/api-keys` | `POST` 创建的密钥限定在同一个域名。`GET` 只列出、`DELETE` 只吊销限定到该域名的密钥；其他密钥会返回 `404`。 |
| 联系人、分群、订阅主题 | 允许。联系人是团队共用的通讯录，但密钥不能撤销团队范围的退订。它创建的分群或订阅主题会绑定到它自己的域名，也不能解除绑定。 |
| Webhook（所有方法，包括签名密钥）、抑制列表、模板、联系人属性、`GET /usage`、`GET /deliverability`、验证和 `POST /domains` | `403 restricted_api_key`：这些属于整个团队。 |

适合只属于某一个品牌的服务：即使泄露，也只能触及该品牌的域名，碰不到你的 Webhook、其他密钥或其他域名。

## 把密钥限定到某个收件箱

收件箱密钥只让 AI agent 访问一个[收件箱](/docs/zh-hans/inboxes)，其他都不行。它需要完全访问权限，不能同时限定到域名，只能为这个收件箱读取、回复、转发和发送草稿，并且只能用该收件箱的地址发信。收件箱过期或被删除后，密钥随之失效。

## 限额

| 限额 | 数值 |
| --- | --- |
| 每个团队的有效密钥数 | 25 个，包括 [SMTP 凭据](/docs/zh-hans/smtp)。要创建新的，先吊销一个（否则返回 `422`）。 |
| 每个收件箱的有效密钥数 | 5 个，不占团队的 25 个名额。 |
| 请求数 | 每个密钥每分钟 600 次，每个团队 3,000 次；见 [API 基础](/docs/zh-hans/api-reference/basics)。 |

## 谁能创建哪种密钥

- 在控制台里，所有者、管理员和开发者可以创建密钥。
- 通过 API 创建的密钥，权限永远不会比创建它的密钥更大：仅发送密钥只能创建仅发送密钥；限定到某个域名的密钥只能为该域名创建密钥（也只能看到和吊销这些密钥）；收件箱密钥不能创建密钥。
- 密钥以其创建者**当前**的团队角色行事，每次请求都会重新检查。创建者是在控制台里创建它的人（或连接了创建它的应用的人）；通过 API 创建的密钥，沿用创建它的那个密钥的创建者。角色不会限制日常工作：无论创建者是什么角色，完全访问密钥都可以发送邮件，并管理联系人、群发、域名、Webhook 和密钥（限定到某个域名的密钥是例外，见上文）。高风险操作（清除收件人、移出抑制列表、撤销退订）需要创建者当前是所有者或管理员的密钥；其他密钥会返回 `403 forbidden`。创建者被降级后，他的密钥从下一次请求起按新角色处理。如果他被移出团队或自己退出，他创建的所有 API 密钥、这些密钥创建的密钥，以及他的 agent 密钥都会立即失效（`401 invalid_api_key`），并显示为已吊销；再次被邀请回来也不会恢复。见[团队角色](/docs/zh-hans/team-roles)。

创建、重命名和吊销密钥都会记录在[审计日志](/docs/zh-hans/audit-log)里。

## 其他密钥

- **SMTP 凭据**是在 **SMTP** 页面为 [SMTP 服务](/docs/zh-hans/smtp)创建的仅发送密钥。
- **Agent 密钥**（`bs_agent_…`）只用于 [MCP 服务器](/docs/zh-hans/mcp)。它们在 **MCP** 下创建，权限限定为只读、读取并回复，或读取并发送，每个团队最多 20 个。你的常规 API 密钥不能用在 MCP 服务器上。
