Logo

這裡提供完整的開發指南與最佳實踐，幫助您快速上手。

教學

API Key 使用教學

從 Header 帶法、環境變數注入、到金鑰輪替與洩漏處置 SOP，整理一段在實務專案中安全使用 API 金鑰的流程。

金鑰是您與 Abestar API 之間唯一的身分憑據。本章不重複介紹如何申請（請見「訪問和身份驗證」），改聚焦在拿到金鑰後該怎麼放、怎麼換、怎麼處理意外。

Header 帶法

所有需要認證的端點都讀 X-API-Key 這個 HTTP Header。範例皆假設您已用環境變數 ABESTAR_API_KEY 持有金鑰。

shell 透過環境變數取金鑰。

bash
# Set once per shell session
export ABESTAR_API_KEY="sk_live_..."

# Use it on every authenticated request
curl -X POST "https://abemono.abestar.com.tw/api/v1/translations/text" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hello", "target_language": "zh-TW" }'

Node 端透過 process.env 取金鑰。

javascript
// Server-side fetch — read from process.env, never bundle the key
const res = await fetch("https://abemono.abestar.com.tw/api/v1/translations/text", {
    method: "POST",
    headers: {
        "X-API-Key": process.env.ABESTAR_API_KEY,
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        text: "Hello",
        target_language: "zh-TW",
    }),
});

金鑰絕對不可放在前端

金鑰落入瀏覽器代表所有人都能拿到。請一律從伺服器端代理請求，或在 BFF 把金鑰加在 server-side 後再轉發。前端打包檔、環境變數 (NEXT_PUBLIC_*、VITE_*)、原始碼公開倉庫都不可寫入金鑰。

金鑰輪替（Key Rotation）

建議每個帳號至少持有兩把金鑰，並以以下流程做無中斷輪替。同時持有多把金鑰是控制台支援的常見用法，舊金鑰撤銷前，新舊金鑰會同時有效。

  1. 在控制台建立新金鑰；舊金鑰暫時保留有效。
  2. 把新金鑰寫入秘密管理工具 / 環境變數，重新部署受影響的服務。
  3. 觀察一段時間（通常 24–72 小時）。確認所有實例都已切換、無 401 unauthorized 增加。
  4. 在控制台撤銷舊金鑰。撤銷後使用舊金鑰的請求一律回 401 unauthorized。

金鑰洩漏處置 SOP

金鑰若意外進入版本控管或前端打包檔，請立刻按以下流程處理。每一步都應記錄時間點，方便事後檢討。

  1. 立刻在控制台撤銷洩漏的金鑰；撤銷不可逆，立即生效。
  2. 建立新金鑰，更新秘密管理工具與部署環境。
  3. 確認所有受影響的儲存庫、git 歷史、CI 紀錄都不再含有舊金鑰。git 歷史殘留時請改寫歷史或重建 repo。
  4. 回查近期使用紀錄是否有異常請求量、未預期的端點呼叫或地理位置變化。
  5. 檢討洩漏路徑，補上預防措施（pre-commit secret scan、env 範本、CI 機密檢查）。