認証とレート制限

オープン プラットフォームのすべてのエンドポイントは、API キーを通じて均一に認証されます。このページでは、トークンを記述する 3 つの方法、パッケージのレート制限、エラー応答のセマンティクスについて明確に説明します。

3つの認証書き込み方式

1.権限：Bearer（推奨）

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

最も標準的な書き込み方法で、すべての SDK でデフォルトでサポートされています。実稼働環境が優先されます。

2.X-API-Key ヘッダー

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

一部の閉じたネットワークのプロキシが認証ヘッダーを転送できないシナリオに適しています。機能的には Bearer と同等です。

3. クエリパラメータ ?api_key= (ヘッダーを書き込めないシナリオのみ)

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 キーには「1 分あたり」と「1 日あたり」の 2 つの上限があり、キー所有者のパッケージに応じて自動的に適用されます。 各キーには独立したクォータがあり、同じアカウント内の他のキーと共有されません。

パッケージ比較表

ウィンドウセマンティクス

• 分窓 · エポック分をキーとして使用し、境界は 1 分ごとに自動的にリセットされます (最初の通話から始まるスライディング ウィンドウではありません)。
• 毎日（日枠） · UTC 日付をキーとして使用し、毎日 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 ヘッダー (秒数) を読み取り、対応する時間だけ遅延してから再試行します。
• X-RateLimit-Window どのウィンドウがヒットしたかを示します (分/日)
• 指数関数的バックオフ + ジッター。 429 を受信した直後に再試行しないでください

HTTPレスポンスコード