API Keys

API Key 用於認證 API 請求，讓外部系統與自動化腳本安全地存取平台資源。

端點概覽

使用場景

• 系統整合：為外部系統建立 API Key 進行資料交換
• 自動化腳本：在 CI/CD 或排程任務中呼叫 API
• 第三方應用：讓合作夥伴存取指定資源

建立 API Key

步驟

1. 登入 SaaS 儀表板
2. 前往 帳號設定 → API Keys (/account/api-keys)
3. 點擊 「建立 API Key」
4. 填寫名稱、說明、權限範圍（Scopes）、過期時間等
5. 確認建立後，系統會顯示完整的 API Key

⚠️ 重要：API Key 只會顯示一次，請立即複製並妥善保存。建議存放於環境變數或密鑰管理系統（如 HashiCorp Vault、AWS Secrets Manager）。

可設定欄位

💡 建立後可透過 API 或前端頁面進行更新、停用、輪換與撤銷。

使用 API Key

在 API 請求的 Authorization Header 中帶入 API Key：

curl -X GET https://api.example.com/api/v1/devices \
  -H "Authorization: Bearer syncai_3rd_Ab3xKm9P_h7sYn2xQkL9..."

Key 格式

syncai_3rd_{prefix}_{secret}

權限範圍 (Scopes)

建立 API Key 時可選擇以下權限範圍，決定該 Key 能存取的資源：

💡 若不指定 scopes，將授予上述全部權限。權限採用 AND 邏輯 — 需同時擁有端點所需的全部權限才能存取。

Key 管理操作

查詢列表

GET /api/v1/api-keys

取得單筆

GET /api/v1/api-keys/{id}

更新

PATCH /api/v1/api-keys/{id}

可更新 name、description、scopes、isActive、rateLimit、allowedIps、metadata。

撤銷

DELETE /api/v1/api-keys/{id}

輪換

POST /api/v1/api-keys/{id}/rotate

輪換後會生成新密鑰；舊密鑰應立即停用並替換部署環境。

安全機制

Rate Limiting 規則

使用 API Key 呼叫端點時，適用以下速率限制：

HTTP Headers

每次回應會包含以下 Rate Limit 資訊：