---
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-hant/team-roles)。需要選擇：

- **名稱**：1 到 80 個字元，用來區分不同的金鑰。之後可以重新命名。
- **權限**：**完整存取**或**僅限傳送**。
- **網域**：**任何網域**，或你團隊的某一個已驗證網域。
- **限制在某個收件匣**（有收件匣之後才會顯示）：金鑰所限定的那一個[收件匣](/docs/zh-hant/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-hant/inboxes)，其他都不行。它需要完整存取權限，不能同時限定到網域，只能為這個收件匣讀取、回覆、轉寄與傳送草稿，而且只能以該收件匣的地址寄信。收件匣過期或被刪除後，金鑰隨之失效。

## 限額

| 限額 | 數值 |
| --- | --- |
| 每個團隊的有效金鑰數 | 25 把，包括 [SMTP 憑證](/docs/zh-hant/smtp)。要建立新的，先撤銷一把（否則回覆 `422`）。 |
| 每個收件匣的有效金鑰數 | 5 把，不佔團隊的 25 個名額。 |
| 請求數 | 每把金鑰每分鐘 600 次，每個團隊 3,000 次；見 [API 基礎](/docs/zh-hant/api-reference/basics)。 |

## 誰能建立哪種金鑰

- 在控制台裡，擁有者、管理員與開發者可以建立金鑰。
- 透過 API 建立的金鑰，權限永遠不會比建立它的金鑰更大：僅限傳送的金鑰只能建立僅限傳送的金鑰；限定到某個網域的金鑰只能為該網域建立金鑰（也只能看到與撤銷這些金鑰）；收件匣金鑰不能建立金鑰。
- 金鑰以其建立者**目前**的團隊角色行事，每次請求都會重新檢查。建立者是在控制台裡建立它的人（或連接了建立它的應用程式的人）；透過 API 建立的金鑰，沿用建立它的那把金鑰的建立者。角色不會限制日常工作：無論建立者是什麼角色，完整存取的金鑰都可以傳送郵件，並管理聯絡人、群發、網域、Webhook 與金鑰（限定到某個網域的金鑰是例外，見上文）。高風險操作（清除收件者、移出抑制清單、撤回退訂）需要建立者目前是擁有者或管理員的金鑰；其他金鑰會回覆 `403 forbidden`。建立者被降級後，他的金鑰從下一次請求起依新角色處理。如果他被移出團隊或自行退出，他建立的所有 API 金鑰、這些金鑰建立的金鑰，以及他的 agent 金鑰都會立即失效（`401 invalid_api_key`），並顯示為已撤銷；再次被邀請回來也不會恢復。見[團隊角色](/docs/zh-hant/team-roles)。

建立、重新命名與撤銷金鑰都會記錄在[稽核日誌](/docs/zh-hant/audit-log)裡。

## 其他金鑰

- **SMTP 憑證**是在 **SMTP** 頁面為 [SMTP 伺服器](/docs/zh-hant/smtp)建立的僅限傳送金鑰。
- **Agent 金鑰**（`bs_agent_…`）只用於 [MCP 伺服器](/docs/zh-hant/mcp)。它們在 **MCP** 下建立，權限限定為唯讀、讀取並回覆，或讀取並傳送，每個團隊最多 20 把。你的一般 API 金鑰不能用在 MCP 伺服器上。
