メインコンテンツへスキップ

API キー

API キーは、Capgo API へのリクエストの認証に使用されます。キーは組織固有で、きめ細かいアクセス制御のために RBAC ロールを割り当てられます。各キーには任意で有効期限を設定でき、プレーンテキストの値が一度しか表示されない「セキュア(ハッシュ化)」キーとして作成することもできます。

各エンドポイントのドキュメントに従って認証ヘッダーを使用してください。API key を使用したリクエストでは、 authorization 以下が受け付けられます:

ターミナル
curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...

一部のエンドポイントでは、専用のキーヘッダーも使用可能です。 API チャンネル は以下を authorization または capgkeyを受け付けます。preview-channel の自動化には、これらのヘッダーのいずれかを使用してください。

API キーは、ユーザーアカウントと同じロールベースのアクセス制御(RBAC)システムを使用します。Webアプリまたは API を通じてキーを作成・管理する際は、以下の2つのレベルでロールを割り当てます。

  • 組織ロール — 組織全体におけるキーの基本権限を定義します(例: org_admin または org_member).
  • アプリのロール — アプリごとの権限(例: app_admin, app_developer, app_uploader, app_reader、または app_preview).

API キーに明示的なロールバインディングが設定されている場合、 権限チェックではそのバインディングのみが 評価されます。キー所有者の個人権限は、キーに継承されません。

プレビューチャンネルの自動化

「Preview channel automation」セクション

Bind app_preview CI用のプレビューアプリにのみ紐付けます。これにより、一時的な非公開のpreview channelを作成し、bundleをuploadおよびpromoteした後、両方を削除します。

{
"name": "PR preview key",
"hashed": true,
"bindings": [
{
"role_name": "app_preview",
"scope_type": "app",
"org_id": "<OWNING_ORG_UUID>",
"app_id": "<APP_UUID>"
}
]
}

org_id は、アプリを所有する組織のUUIDです。 app_id は、アプリレコードの内部UUIDです。CLI コマンドで使用される公開アプリ識別子ではありません(例: com.example.app)。このbindingは、キーに組織全体のロールが付与されていない場合でも、組織に紐付けられた状態が維持されます。

アプリレベルの app_preview roleには以下のみが含まれます: app.read, app.read_bundles, app.upload_bundleや app.create_channel。そのキーがchannelを作成すると、Capgo は自動的に channel_preview を新しく作成されたchannelにbindingします。この子bindingによって、 channel.read, channel.promote_bundleや channel.delete キーが作成したチャンネルのみに限定されます。

app_preview を保持するためです app.read、そのため、これは厳密なチャンネル読み取りの分離ではありません。キーは選択したアプリ内のチャンネルメタデータを列挙できる可能性があります。自動の子バインディングにより、 ライフサイクル変更が キーが作成したチャンネルのみに制限されます。

Capgo は、各bundleをアップロードしたApp Previewキーを記録します。このキーは、自身が作成する各プレビューチャンネルに対して、自身のbundleのみをpromoteできます。既存のデフォルト/メインチャンネル、他のプレビューキーが作成したチャンネル、他のキーのbundleには、チャンネルライフサイクルへのアクセス権がありません。このワークフローでは、 public を省略し、 --default.

使用する channel delete <preview-channel> <public-app-id> --delete-bundle をクリーンアップには決して使用しないでください。これは、アトミックで所有権チェック付きのプレビュークリーンアップルートです。呼び出し元キーのプレビューチャンネルと、リンクされたbundleのみを削除します。 app_preview 汎用的なアクセス権は付与しません。 bundle.delete.

ダッシュボードでの設定と、完全な CLI の例については、以下を参照してください。 プレビューワークフローではApp Previewキーを使用してください.

RBAC API キーの権限の仕組みを示す図

API キーを使用した Organization の作成には、現在、明示的なグローバル権限が必要です: org.create.

この権限は、通常の org/app ロールバインディングとは異なります。なぜなら、呼び出し時に POST /organization/ 新しい organization がまだ存在しないためです。API キーで organization を作成するには:

  • API キーに以下を含める必要があります org.create における global_permissions.
  • 同じ API キーには、現在有効な組織スコープの org_admin または org_super_admin バインディングも必要です。
  • 新しい API キーには、デフォルトでは org.create 付与されません。有効にするには、 「組織の作成を許可する」を ダッシュボードで RBAC API キーを作成または編集する際にオンにしてください。
  • 既存の書き込み可能な組織管理者/スーパー管理者の API キーには、 org.create 既存のインテグレーションが引き続き組織を作成できるよう、権限がバックフィルされました。

API キーが組織を作成すると、Capgo は自動的にその同じ API キーを org_super_admin 新しく作成された組織に割り当てます。これにより、インテグレーションは別途手動でロールをバインドすることなく、作成したばかりの組織を管理できるようになります。

API 経由で API キーを作成する場合は、次を global_permissions org admin バインディングと併せて含めてください:

{
"name": "Provisioning key",
"hashed": true,
"bindings": [
{
"role_name": "org_admin",
"scope_type": "org",
"org_id": "00000000-0000-0000-0000-000000000000"
}
],
"global_permissions": ["org.create"]
}

org.create 組織の作成にのみ適用されます。組織の削除には引き続き、対象組織に対する削除権限が必要で、通常は次を経由します: org_super_admin.

セキュアキーを作成すると、サーバーがキーマテリアルを生成し、平文の値を一度だけ返します。保存されるのはハッシュのみです。つまり:

  • 平文のキーは 作成後に取得することが できません。
  • 再生成すると、新しい平文キー(一度だけ表示)が生成され、保存されているハッシュが更新されます。
  • 本番環境ではハッシュ化キーの使用を推奨します。

一部の組織では、ハッシュ化キーの使用を enforce_hashed_api_keys 組織ポリシーで強制しています。

キーには任意で有効期限を設定できます。期限切れのキーは権限チェック層で拒否されます。

組織ポリシーで強制できる項目:

  • 有効期限の必須化 (require_apikey_expiration) — すべての新規キーに有効期限が必要です。
  • 最大TTL (max_apikey_expiration_days) — 有効期限は現在からN日を超えて設定できません。

セキュリティのベストプラクティス

「セキュリティベストプラクティス」セクション
  1. 最小権限の原則: 連携機能を維持できる範囲内で、最も制限の強いロールを割り当ててください
  2. 定期的なローテーション: 再生成機能を使用して、API キーを定期的にローテーションしてください
  3. セキュアストレージ: API キーは安全に保管し、バージョン管理システムには絶対にコミットしないでください
  4. ハッシュ化されたキーの使用: 本番環境の連携には、安全な(ハッシュ化された)キーを作成してください
  5. 有効期限の設定: 一時的なアクセスや CI/CD 用のキーには、必ず有効期限を設定してください
  6. スコープの制限: キーの使用範囲を特定のアプリに限定し、最小限のロールを割り当ててください
  1. CI/CD 連携: 特定のアプリに限定したキーを、以下の app_uploader または app_developer ロールで作成し、有効期限を設定します。
  2. PRプレビューチャネル: 使用する app_preview CIがbundleをアップロードする必要があるときに、プレビューアプリのみに対して、一時的なチャネルを作成し、自身のチャネルとbundleをアトミックにクリーンアップします。
  3. デプロイの自動化: 次のロールのキーは app_developer 自動デプロイスクリプト用のロール。
  4. モニタリングツール: 次のロールでキーを作成します app_reader 外部モニタリング連携用のロール。
  5. 管理者アクセス: 次のロールのキーは org_admin 管理ツールでは最小限に使用してください。
  6. サードパーティ連携: 特定のアプリに限定し、必要最小限のロールを付与したキーを作成します。
  7. 組織プロビジョニング: 次のロールで org_admin または org_super_admin RBACキーを使用します。 org.create 組織を作成する必要がある、信頼済みの自動化専用です。

使用している場合 API キー 認証とアカウントフローを計画するには、これを次と連携させてください @capgo/capacitor-social-login @capgo/capacitor-social-login の実装の詳細については、 @capgo/capacitor-passkey @capgo/capacitor-passkey の実装詳細については、 @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric の実装の詳細については、 2要素認証 二要素認証の実装の詳細については、また、 SSO (エンタープライズ) SSO (Enterprise) の実装の詳細については。