APIキー管理
Token の形式、作成フロー、8 つの権限スコープ（scopes）、ライフサイクル、使用量分析、セキュリティのベストプラクティス。
API キーは、Braidrun オープン プラットフォームと通信するための唯一の認証情報です。各キーには、一連のスコープ (権限スコープ) とトークンが含まれます。紛失または漏洩した場合、新規作成は直ちに取り消されます。
トークンの形式
text
dyk_<id>_<secret>
例：dyk_a3b9c8d7e6f5a1b2_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789dyk_— git Secret-scanning / ログ非感作ツールを識別できるようにするブランド プレフィックス<id>— 16 文字の base62 公開 ID で、lookup key として使用できます（機密ではありません）<secret>— 32 バイトのランダム シークレット、base64url エンコード (機密性があり、ログ/エラー メッセージのアップロードは許可されません)
トークンは一度だけ表示されます
API キーを生成するとき、元のトークンは作成ダイアログ ボックスに 1 回だけ表示されます。閉じた後、サーバーは Argon2id ハッシュのみを保持し、元のテキストを確認することはできません。今すぐキー管理ツール (1Password/Vault/Doppler/GitHub Secrets/など) にコピーして保存してください。
APIキーの作成
- コンソール → アカウント設定 → API キーにアクセスします。
- 「新しいAPIキー」をクリックします
- 記入：氏名（識別用）、範囲リスト、有効期間（永久/30日/90日/1年）
- 「キーの生成」をクリック→今すぐトークンをコピー
スコープ
Scope はきめ細かい権限で、全 8 種類あります。7 種類はセルフサービスで付与でき、CLUSTER_ADMIN は管理者専用です。1 つの Key に付与する権限は少ないほど良く、最小権限の原則に従います。
| Scope | 何ができるか | 代表的なシナリオ |
|---|---|---|
WEBHOOK_TRIGGER | このキーにバインドされた Webhook をトリガーします | GitHub プッシュ → ワークフロー;上流のビジネス システム コールバック |
APPROVAL_RESPOND | manual_approval ステップの承認 / 却下 — 承認 Webhook と v1 承認エンドポイント（/api/v1/approvals/*、承認待ちの一覧表示、詳細の読み取り、編集後の承認フォームの送信を含む）をカバーします | メール / Slack のワンクリック承認リンク、外部承認システムとの連携 |
WORKFLOW_READ | ワークフロー定義の一覧表示/読み取り | 現在のワークフローリストを外部ダッシュボードに表示します |
WORKFLOW_EXECUTE | API経由でワークフローを開始（Webhookモードの置き換え） | SDKの統合。自動テスト。バッチタスク |
EXECUTION_READ | クエリ実行ステータス/読み取り完了結果 | 実行結果をエンタープライズBI/データウェアハウスにバックフロー |
EXECUTION_CANCEL | 実行中の実行をキャンセルする | 管理パネルの「停止」ボタン／非常用ブレーカー |
ARTIFACT_READ | 実行製品の一覧表示/ダウンロード リンクの取得 | レポートをオブジェクト ストレージにアーカイブします。結果を下流システムにプッシュする |
CLUSTER_ADMIN | 管理者専用: クラスターの状態の読み取り、オートスケーリングポリシーの管理を行います。付与できるのは管理者のみです。管理者以外が Key を作成する場合、この scope は自動的に除去されます | オンプレミス展開の運用サービスアカウント |
ライフサイクル
- 作成する — ユーザーのセルフサービス。範囲 + 有効期間はお客様が決定します
- 使用する — 呼び出しが成功するたびに、使用量が自動的に蓄積され、lastusedAt タイムスタンプが更新されます。
- Revoke — ユーザーはいつでも「API キー」ページの「取り消し」をクリックできます。冪等
- 有効期限 — expiresAt は到着後すぐに期限切れになります。積極的な取り消しは必要ありません
投与量分析
各キーについて、「API キー」テーブルの「使用状況」をクリックすると、チャート分析がポップアップ表示されます。
- 累積通話数 + 期間内 (7/30/90/180 日間オプション)
- ピーク日（通話が最も多い日）
- 毎日のコールの折れ線グラフ
- コールエンドポイント分布円グラフ (webhook.trigger/workflow.execute/etc)
- 最後に使用した時間
使用量は成功した応答 (HTTP 2xx) のみをカウントします。認証の失敗/レート制限されたリクエストはカウントされません。
主要なセキュリティのベスト プラクティス
に従ってください
- 各環境 (本番/ステージング/ローカル) に独立したキーを使用します。インシデントが発生した場合、影響を受ける環境のみが取り消されます。
- 各外部統合は個別のキーを使用します。どの統合が使用されているかを確認するには、「使用状況」を使用します。
- トークンをコード リポジトリに送信しないでください
- 暗号化されたシークレットとして CI/CD に挿入します。ログに出力しない
- 「最近使用した」時間が予想と異なることを確認します → すぐに取り消してログを確認してください
- 短期パートナーに与えられるキーは、expiresAt に設定する必要があります (90 日以内を推奨)