API Hop

文件目錄

API Hop 文件

安全與設定

API 金鑰建立、權限控制、輪替與安全實務。

保護 API 金鑰的核心原則是：不外露、採最小權限、定期輪替，並保持用量可追蹤。

如何管理及保護 API 金鑰？

建議做法：

  • 不要將金鑰提交至公開儲存庫、前端頁面、行動應用套件或螢幕截圖。
  • 在伺服器從環境變數或機密管理系統讀取金鑰。
  • 為開發、測試及正式環境建立不同金鑰。
  • 為不同服務或應用建立獨立金鑰，改善追蹤與隔離。
  • 依需要設定模型權限，並於適當情況設定到期日。
  • 定期輪替金鑰；人員異動、服務停止或疑似外洩時立即輪替。

若金鑰可能已外洩：

  1. 立即停用、刪除或輪替舊金鑰。
  2. 建立新金鑰並更新所有相依服務。
  3. 檢查近期用量、餘額變化及異常支出。
  4. 縮減模型權限，並考慮較短的有效期限。
  5. 檢查外洩途徑，例如儲存庫、日誌、CI 設定或第三方用戶端。

金鑰外洩可能造成未授權呼叫及費用損失。即使是測試金鑰，也應如同正式環境機密般保護。

建立後還能再次查看完整 API 金鑰嗎？

不能。完整金鑰只在成功建立流程中顯示。之後控制台只顯示遮蔽預覽。

關閉建立視窗前，請將金鑰儲存在伺服器端環境變數或機密管理系統。遺失的金鑰無法透過使用者或管理員 API 復原。請建立替代金鑰、更新呼叫端，再刪除舊金鑰。文件的 AI 串接範本使用 <API_KEY> 佔位符，不會載入歷史金鑰。

如何傳送 API 金鑰？

只透過請求標頭傳送金鑰。我們建議：

http
Authorization: Bearer YOUR_API_KEY

也可以使用：

http
X-API-Key: YOUR_API_KEY

絕不要將 RequestBeam API 憑證放進 URL 查詢參數。憑證類名稱（apiKey、api_key、apikey、x-api-key 及 key）通常會觸發 HTTP 400。 有限的 Similarweb 業務參數例外僅適用於 GET 請求： /v1/similarweb/websites/backlinks 接受一個大寫 Key 主機名稱； /v1/similarweb/websites/outgoing-traffic、/websites/incoming-referrals 及 /websites/similar-sites/suggestions 接受一個小寫 key 主機名稱 （皆位於 /v1/similarweb 下）。這些欄位識別目標網站，不是 API 憑證。主機名稱必須有效。重複值、錯誤大小寫、類似憑證的值，以及額外憑證查詢欄位仍會被封鎖。 務必以請求標頭驗證身分，包括 Similarweb 路由。 請參閱 Similarweb 請求範例。

此規則不影響 OAuth token、apiKeyId、username 或 pagination_token 等其他業務參數。