鑑權與速率限制

開放平台所有端點統一透過 API Key 鑑權。本頁講清楚三種 Token 寫法、套餐速率限制、以及錯誤回應的語意。

三種鑑權寫法

1. Authorization: Bearer（推薦）

curl https://braidrun.com/api/v1/workflows \
  -H "Authorization: Bearer dyk_<id>_<secret>"

最標準的寫法，所有 SDK 預設支援。生產環境優先使用。

2.X-API-Key Header

curl https://braidrun.com/api/v1/workflows \
  -H "X-API-Key: dyk_<id>_<secret>"

適合某些封閉網路的代理人無法轉送 Authorization Header 的場景。功能等同於 Bearer。

3. Query 參數 ?api_key=（僅限不能寫 Header 的場景）

https://braidrun.com/api/webhook-trigger/approval/appr-123/approve?api_key=dyk_<id>_<secret>

優先級

1. Authorization: Bearer dyk_…
2. X-API-Key: dyk_…
3. ?api_key=dyk_…

從上到下依序嘗試，找到一個非空就停止解析。

速率限制

每個 API Key 各自有「每分鐘」和「每日」兩個上限，按 Key owner 的套餐自動應用。 每個 Key 獨立配額，不與同賬號的其他 Key 共享。

套餐對照表

視窗語義

• 每分鐘（minute window） · 使用 epoch 分鐘做 key，每分鐘邊界自動重置（不是從第一次調用算起的滑動窗口）
• 每日（day window） · 使用 UTC 日期做 key，每日 00:00 UTC 自動重置

達到限額時

HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 60
X-RateLimit-Window: minute
Content-Type: application/json

{
  "error": "Rate limit exceeded",
  "window": "minute",
  "limit": 60,
  "retryAfterSeconds": 38
}

客戶端應當：

• 讀取 Retry-After Header（秒數），延遲相應時長後再重試
• X-RateLimit-Window 告訴您是哪個窗口被命中（minute / day）
• 指數退避 + jitter；不要在收到 429 後立即重試

HTTP 回應碼