文件

API 金鑰

產生並管理用於程式化存取的 API 金鑰。

API 金鑰可讓你以程式化方式存取你的代理程式。你可以用它們將 Agentkit 整合到你的應用程式中，或連接第三方服務。

建立金鑰與使用 API 需要 Hobby 方案或以上，且帳單狀態為有效。工作區成員失去此存取資格後，仍可檢視及撤銷現有金鑰。 升級你的方案 →

建立 API 金鑰

  1. 前往你的工作區
  2. 在側邊欄點選API 金鑰
  3. 點選建立 API 金鑰
  4. 在對話方塊中確認

新的金鑰會出現在清單中，你可以隨時顯示或複製它。

檢視與複製金鑰

清單中的每組金鑰預設都會遮蔽顯示。你可以使用眼睛圖示顯示金鑰，並使用複製圖示將其複製到剪貼簿。

使用 API 金鑰

在 API 請求中加入此金鑰：

curl -X POST 'https://your-domain.com/api/v1/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"chatbotId": "uuid", "messages": [{"role": "user", "content": "Hello"}]}'

完整 API 文件 →

管理金鑰

檢視所有金鑰

工作區的所有金鑰都會列在 API 金鑰頁面上。

刪除金鑰

  1. 在清單中找到該金鑰
  2. 點選垃圾桶圖示
  3. 確認刪除

已刪除的金鑰會立即停止運作。

存取資格到期後撤銷金鑰

如果工作區失去 API 存取權，請登入並在 API 金鑰 頁面刪除不再需要的金鑰。撤銷金鑰不需要續訂付費方案。你仍必須是該工作區的成員。如果你已啟用 MFA，請先完成 MFA 驗證，再管理金鑰。在完成驗證之前，資料庫會隱藏工作區的金鑰並拒絕刪除。這不會恢復 API 使用權或建立金鑰的權限。

Agentkit 過去會在刪除金鑰前檢查付費 API 存取資格。資料庫政策也要求具備此資格才能讀取或刪除金鑰。因此，失去存取權可能會阻止清除現有憑證。

此修正將建立與清除分開處理。工作區成員資格決定現有金鑰的讀取和刪除權限，另以獨立的資料庫政策強制執行 MFA。建立及更新金鑰仍需要 API 存取資格。刪除操作會同時比對金鑰 ID 與工作區 ID，只有在資料庫傳回已刪除的資料列時才回報成功。

以下簡化範例說明存取檢查的變更：

Before
  Require API entitlement before deleting an existing key.

After
  Delete only a key belonging to the requested workspace.
  Require a returned deleted row before reporting success.
  Keep membership checks and enforce MFA in the database.

應用程式測試會模擬資料庫用戶端，檢查篩選條件和結果處理，而非資料庫政策。SQL 測試使用合成帳戶，並回復變更。預期結果包括：

檢查測試層級預期結果
授權成員在沒有 API 存取資格時撤銷金鑰應用程式模擬不查詢存取資格；依金鑰和工作區篩選；成功必須傳回資料列
授權成員在沒有 API 存取資格時撤銷金鑰SQL刪除一個所屬工作區的金鑰
成員在沒有存取資格時建立金鑰應用程式模擬與 SQL拒絕
成員嘗試刪除其他工作區的金鑰SQL未刪除任何資料列
未滿足必要的 MFA 要求SQL未刪除任何資料列
要求的金鑰不存在或呼叫者無法看見應用程式模擬操作回報失敗

這些是回歸測試的預期結果，不是正式環境試驗結果。代理工作流程中的暫時憑證也可採用相同測試模式。先變更存取權，再進行清理，並確認授權清理成功、未授權清理遭到拒絕。

安全性最佳做法

絕不外洩金鑰

  • 請勿將金鑰提交至 Git 版本庫
  • 請勿將金鑰放入用戶端程式碼中
  • 請使用環境變數

定期輪替金鑰

  • 定期建立新的金鑰
  • 更新你的應用程式
  • 刪除舊的金鑰

使用個別金鑰

請為以下情境建立不同的金鑰：

  • 正式環境與開發環境
  • 不同的應用程式
  • 不同的團隊成員或服務

金鑰範圍

API 金鑰的範圍僅限於建立時所在的工作區，並可存取：

  • 工作區中的所有代理程式
  • 聊天 API 端點
  • Webhook 管理

金鑰無法：

  • 管理團隊成員
  • 存取帳單
  • 建立其他 API 金鑰

Zapier 連接

連接至 Zapier 時：

  1. 為 Zapier 建立一組專用的 API 金鑰
  2. 在 Zapier 連接中使用此金鑰
  3. 讓此金鑰保持專用，不與其他用途共用

設定 Zapier →

疑難排解

「Invalid API key」錯誤

  • 確認金鑰複製正確
  • 檢查前後是否有多餘的空格
  • 確認金鑰尚未被刪除

「Key not authorized」錯誤

  • 確認該代理程式屬於你的工作區
  • 檢查金鑰所屬的工作區是否相符
  • 針對 API 請求，確認你的工作區方案為 Hobby 或以上，且帳單狀態為有效

金鑰建立後無法運作

  • 嘗試重新整理頁面
  • 等待 30 秒讓設定生效
  • 若問題持續發生，請建立新的金鑰

後續步驟