開發者
身份認證
建立 sk_ API 金鑰，為每個請求做認證，並在不影響生產環境的前提下輪換或過期金鑰。
一個金鑰解鎖整套 API。 對 Buda REST API、MCP 端點以及嵌入流程的每一個請求，都使用與你賬戶繫結的同一個 API 金鑰進行認證。在控制台裡建立一次，將它作為 Bearer 令牌傳送，幾分鐘內你就能呼叫託管智慧體。
建立 API 金鑰
開啟「設定 → API 金鑰」
在控制台中，進入 設定 → API 金鑰，選擇 新建金鑰。
命名並設定有效期
為金鑰起一個易於辨識的名稱（例如 production-backend），並選擇有效期：永不過期、7 天、30 天、90 天 或 365 天。短期金鑰用於測試和 CI 更安全。
立即複製金鑰
完整金鑰——以 sk_ 為字首——只在建立後顯示一次。請立即把它複製到你的金鑰儲存中；此後 Buda 只儲存一個打碼版本，因此金鑰再也無法被重新顯示。
如果你錯過了這次一次性顯示，請刪除該金鑰並重新建立一個。之後無法找回完整的金鑰值。
使用金鑰
將金鑰作為 Bearer 令牌放在 Authorization 請求頭中。基礎 URL 為 /api/v1。
# 驗證你的金鑰能否解析到你的賬戶
curl https://buda.im/api/v1/users/me \
-H "Authorization: Bearer sk_your_api_key"// Node / TypeScript
const API_BASE = "https://buda.im/api/v1";
const headers = {
Authorization: `Bearer ${process.env.BUDA_API_KEY}`,
"Content-Type": "application/json",
};
const me = await fetch(`${API_BASE}/users/me`, { headers }).then((r) => r.json());有效的金鑰會解析到其所屬使用者；缺失或無效的金鑰會返回 401 Unauthorized。Buda 會記錄每個金鑰最近一次請求的時間，方便你在刪除金鑰之前判斷它是否仍在使用中。
輪換與過期
- 有效期 在建立時設定，且無法延長。要「續期」，請建立一個新金鑰並停用舊的。
- 輪換 的做法是：先建立替換金鑰，部署上線，然後再刪除舊金鑰——這樣服務不會中斷。
- 刪除 金鑰可隨時在 設定 → API 金鑰 中進行。刪除立即且永久生效：使用該金鑰的進行中請求會立刻開始失敗。
安全最佳實踐
- 像對待生產金鑰一樣對待 API 金鑰。 切勿把它們硬編碼進前端或移動端程式碼，也切勿提交到程式碼倉庫。
- 隔離不同環境。 為測試、預釋出和生產使用各自獨立的金鑰，這樣吊銷其中一個不會影響其他環境。
- 絕不要把金鑰傳送到瀏覽器。 對於客戶端的智慧體對話，請使用短期嵌入令牌，而不是你的
sk_金鑰。 - 洩露即輪換。 如果某個金鑰可能已洩露，請立即刪除它並簽發新的金鑰。