鉴权与速率限制

开放平台所有端点统一通过 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 响应码