API キー
インストール手順と、このプラグインの完全なMarkdownガイドを含むセットアッププロンプトをコピーします。
API キーは、Capgo API へのリクエストの認証に使用されます。キーは組織固有で、きめ細かいアクセス制御のために RBAC ロールを割り当てられます。各キーには任意で有効期限を設定でき、プレーンテキストの値が一度しか表示されない「セキュア(ハッシュ化)」キーとして作成することもできます。
API key の使用方法
「API key の使用方法」というセクション各エンドポイントのドキュメントに従って認証ヘッダーを使用してください。API key を使用したリクエストでは、 authorization 以下が受け付けられます:
curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...一部のエンドポイントでは、専用のキーヘッダーも使用可能です。 API チャンネル は以下を authorization または capgkeyを受け付けます。preview-channel の自動化には、これらのヘッダーのいずれかを使用してください。
RBAC 権限
「RBAC権限」セクション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キーを使用してください.

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