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

# 身分驗證與權限範圍

> 安全地使用 bearer API 金鑰與最小必要權限範圍。

Brightalk REST API 以 bearer API 金鑰驗證伺服器對伺服器的請求。金鑰會決定請求所屬的組織，以及可執行的操作。

## 傳送 bearer 金鑰

每個請求都必須在 `Authorization` 標頭傳送金鑰。語法必須完全符合：`Bearer`、一個空格，再接金鑰。

```http theme={null}
Authorization: Bearer $BRIGHTALK_API_KEY
```

缺少 bearer 標頭或格式錯誤時會傳回 `401 authentication_required`。語法正確、但找不到或已撤銷的金鑰，則傳回 `401 invalid_api_key`。

## 建立及保存金鑰

請在 [Brightalk API 設定](https://www.brightalk.ai/settings/integrations/api)建立 `bt_live_` 金鑰。完整金鑰只會顯示一次；請直接複製到伺服器端金鑰管理工具，切勿放進版本控制、日誌、瀏覽器儲存空間、行動裝置程式碼或傳送給客戶端的環境變數。

需要時請選擇到期日。超過到期日的金鑰會傳回 `401 api_key_expired`。撤銷會對後續請求生效；若懷疑金鑰外洩或暫時測試已完成，應立即撤銷。

## 選擇最小必要權限範圍

每個操作都會檢查權限範圍，且預設拒絕未授權操作。寫入或執行權限不包含相對應的讀取權限，讀取權限也不包含寫入權限。

| 資源                  | 讀取權限範圍                            | 寫入或執行權限範圍         |
| ------------------- | --------------------------------- | ----------------- |
| 代理目錄（`GET /agents`） | `calls:read` **或** `batches:read` | —                 |
| 聯絡人                 | `contacts:read`                   | `contacts:write`  |
| 通話                  | `calls:read`                      | `calls:write`     |
| 批次                  | `batches:read`                    | `batches:write`   |
| 自動化                 | `automations:read`                | `automations:run` |

`GET /agents` 是目錄的例外：`calls:read` 或 `batches:read` 任一權限即可通過驗證（`anyOf`）。只有在伺服器需要建立或啟動工作，並接著查詢工作時，才選取同一資源的兩項權限。這只是方便整合的建議配對，不表示兩個權限範圍會彼此隱含。

## 安全地輪替及撤銷

先建立只具最小必要權限範圍的替代金鑰，更新伺服器端金鑰並確認替代金鑰能成功請求，再撤銷舊金鑰。兩把金鑰重疊有效期間都不可暴露。輪替不會改變資源歸屬，也不會繞過既有的冪等性宣告。

## 謹慎使用互動式 GET 測試工具

<Warning>
  在互動式 GET 測試工具輸入的金鑰會經過 Mintlify 代理伺服器。請使用暫時且僅具最小必要讀取權限的金鑰，不要加入寫入／執行權限，並在測試後立即撤銷。
</Warning>

寫入端點只提供可複製的範例，不提供互動式寫入控制。一般整合應由您的伺服器直接向 `https://api.brightalk.ai` 傳送所有請求。