API 認証 (API Key)

Public API は API Key 認証で利用します。組織管理者が 管理 → API Key から発行・管理します。

API Key を発行する

管理 → API Key 画面を開く

組織管理者（org_admin）以上の権限を持つアカウントでログインし、サイドバーから「API Key」を選択します。

「新規発行」をクリック

名前（用途のメモ）・スコープ・有効期限（任意）を入力します。

表示された Key をコピー

API Key は発行直後にしか表示されません。 必ずパスワードマネージャーやシークレットマネージャーに保存してください。Key を紛失した場合は rotate（再発行）が必要です。

リクエストヘッダに付与

すべての保護エンドポイントで X-API-Key: ac_live_... をヘッダに付けて送信します。

スコープ一覧

Key 発行時に最小権限のスコープのみを付与してください。読み取りだけが必要な連携には workflows:read + executions:read で十分です。

スコープ	許可される操作
`workflows:read`	ワークフロー一覧・詳細・Webhook URL 取得
`workflows:write`	ワークフローの作成・更新・削除
`executions:execute`	ワークフローの実行（POST `/workflows/{id}/execute`）
`executions:read`	実行履歴の取得

API Key は組織内の権限と同等以下に制限されます。org_admin が発行した Key でも、別組織のリソースにはアクセスできません（404 が返ります）。

Idempotency-Key（冪等性キー）

書き込み・実行系（POST /workflows, POST /workflows/{id}/execute）では Idempotency-Key ヘッダの利用を推奨します。ネットワーク不調で同じリクエストが 2 回到達しても、サーバ側で重複実行を防ぎます。

curl -X POST https://app.pigeon-workflow.ai/api/v1/workflows/123/execute \
  -H "X-API-Key: ac_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \   # UUID v4 推奨
  -H "Content-Type: application/json" \
  -d '{"input_data": {...}}'

同一の Key で 24 時間以内に再リクエストすると、初回と同じレスポンスが返ります。
異なるリクエストボディで同じ Key を送ると 409 Conflict になります。

運用ベストプラクティス

Key は ソースコードや Slack に貼らず、シークレットマネージャー（Secrets Manager / Vault / GitHub Actions secrets 等）に保存する
用途別に Key を分け、不要になったら revoke する（誰のために発行したか追跡しやすくなります）
定期的（90 日推奨）に rotate する。管理画面の「Rotate」ボタンで新 Key 発行 + 旧 Key を 24 時間有効のまま並走できます
監査ログ（管理 → API Key → ログ）で送信元 IP・スコープ違反の試行を定期確認する
連続失敗で Key が自動ロックされた場合は、管理画面で Unlock 操作が必要です