本文へスキップ
ホーム/Public API/認証 (API Key)
Public API

API 認証 (API Key)

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

この記事の内容

  1. API Key を発行する
  2. スコープ一覧
  3. Idempotency-Key
  4. 運用ベストプラクティス

API Key を発行する

1

管理 → API Key 画面を開く

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

2

「新規発行」をクリック

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

3

表示された Key をコピー

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

4

リクエストヘッダに付与

すべての保護エンドポイントで 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 回到達しても、サーバ側で重複実行を防ぎます。

cURLexecute.sh
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 操作が必要です

前の記事
Public API 概要