APIキー

APIキーを使うと、エージェント、CLI、SDK、下流システムがあなたとしてBusabaseの /api/v1 APIにプログラムからアクセスできます。キーは認証情報のひとつで、何ができるかは作成時に選んだ権限レベルで決まり、有効期限が切れるか削除するまで有効です。

APIキーの作成 — 名前・有効期限・権限レベルは作成時にまとめて決めます。

APIキーを作成する

有効期限

既定は 30日間、最長は 1年間 です。有効期限が切れたキーでリクエストすると 401 が返るため、新しいキーを作成してください。

権限レベル

キーには権限レベルがひとつだけ設定され、上位のレベルは下位のすべてを含みます：

エージェントに使うなら、通常は changeRequest で十分です。 データを読み、変更を提案できますが、自分の提案を自分でマージすることはできません — 変更は受信トレイで人がレビューします。本当に必要な場合にだけ write や manage を付与してください。

作成後も名前の変更と権限レベルの変更ができます。キーの値と有効期限は変わりません。権限を引き上げる際は二段階の確認があり、既存の利用者全員がすぐに新しい権限を得るためです。

キーとワークスペースの関係

キーは特定のワークスペースではなく、あなたのアカウントに属します — あなたが所属するすべての workbench スペース（Bases、レコード、Change Request、ノード）で使えます。

対象のスペースを指定するには、リクエストに x-busabase-space ヘッダーを付けます（CLI / SDK では環境変数 BUSABASE_SPACE_ID）。複数のスペースに所属していて指定しない場合、リクエストは対象が曖昧として拒否されます。Busabase が推測することはありません。

GET /api/v1/auth を呼ぶと、現在有効なスペースと、あなたが所属するすべてのスペースを確認できます。

また、権限レベルは上限です。実際にできることは、そのスペースでのあなたのロール権限との積になります。

リクエストで使う

キーは Authorization ヘッダーに入れます：

curl https://busabase.com/api/v1/auth \
  -H "Authorization: Bearer $BUSABASE_API_KEY" \
  -H "x-busabase-space: $BUSABASE_SPACE_ID"

• ベースURL：https://busabase.com（ローカルやセルフホストでは該当するアドレス）。
• 認証ヘッダー：Authorization: Bearer <key>。x-api-key も使用できます。
• レコードの書き込み：/api/v1 経由で送信すると、レコードはレビューのため受信トレイに入ります。

リクエストの形式と例は REST API、全エンドポイントは OpenAPI リファレンス を参照してください。

セキュリティの実践

• エージェントごとに1つのキー。 複数のエージェントで1つのキーを共有しないでください。権限と利用量を区別できなくなります。キーを分けておくと、Busabase Insights で各エージェントがどの Change Request や提案を行ったかを確認できます。
• 最小権限。 作業を完了できる最も低いレベルから始め、必要になったら別のキーを発行します。
• 有効期限を設定する。 一時的なタスクには短期のキーを、長期の連携には定期的なローテーションを。
• リポジトリに含めない。 CI やローカル開発では環境変数で渡します（BUSABASE_API_KEY、BUSABASE_SPACE_ID）。
• 漏洩が疑われたらすぐ削除。 削除すると、そのキーを使うすべての呼び出し元が即座に認証できなくなります（下記参照）。

管理と失効

Account → API Keys の一覧には、各キーの名前、キーのプレフィックス、作成日、有効期限、権限レベル、操作が表示されます。

• コピー：作成直後のみ可能です。その後、完全なキーを再表示することはできません。
• 編集：名前または権限レベルを変更します。
• 削除：即座に失効し、元に戻せません。そのキーを使う連携はすぐにアクセスできなくなり、新しいキーが必要です。

トラブルシューティング

関連: コアコンセプト · クイックスタート

その他の接続方法：連携方法の一覧 · CLI · SDK · MCP · REST API · OpenAPI · Webhook