API キー

APIキーは、Capgo APIへの要求を認証するために使用されます。キーは組織固有であり、RBACロールを割り当てることで細かいアクセス制御が可能です。各キーには期限日付もオプションで設定でき、セキュア（ハッシュ）キーとして作成することも可能で、平文値は一度だけ表示されます。

APIキーを使用する

APIキーを使用する場合、ドキュメントされた認証ヘッダーを使用してください。APIキー要求の場合、 authorization 受け入れられる:

curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...

一部のエンドポイントでは、専用のキーヘッダーも受け入れられます。 チャンネル API 受け入れる authorization または capgkeyチャンネルを選択して、__CAPGO_KEEP_0__ を使用してプレビュー チャンネル自動化を実行します。

RBAC 権限

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

• 組織ロール 組織全体の基準となる権限を定義します (例えば、 org_admin または org_member).
• アプリ ロール アプリごとの権限 (例えば、 app_admin, app_developer, app_uploader, app_reader、または app_preview).

API キーが明示的なロールのバインドを持つ場合 バインドされるのは それだけです。キー所有者の個人的な許可は、キーによって継承されません。

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

バインド app_preview CI が作成する一時的な非公開のプレビュー チャンネル、バンドルをアップロードし、プロモートし、両方を削除するプレビュー アプリにのみバインドします。

{
  "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)。バインドは、キーが組織全体のロールを持たない場合でも組織に依存します。

アプリケーションレベルの app_preview ロールには app.read, app.read_bundles, app.upload_bundle、および app.create_channel。キーがチャネルを作成すると、Capgoは自動的に新しいチャネルに channel_preview を追加します。その子孫の channel.read, channel.promote_bundleは channel.delete 、および

app_preview のみがチャネルを作成したキーに許可されます。 app.readは を保持します。したがって、これは厳格なチャネル読み取り隔離ではありません: キーは選択したアプリのチャネルメタデータを列挙できます。 のライフサイクル変化は

Capgo records the App Preview key that uploaded each bundle. The key can promote only its own bundle to each preview channel it creates. It has no channel lifecycle access to an existing default/main channel, a channel created by another preview key, or another key’s bundle. For this workflow, omit public そして、いつも使用しない --default.

使用 channel delete <preview-channel> <public-app-id> --delete-bundle クリーンアップ用途に使用します。このルートは、所有権のチェックされた原子的なプレビュー クリーンアップルートです。呼び出し元のキーが使用しているプレビュー チャネルとリンクされたバンドルだけを削除します。 app_preview 一般的な権限を付与しない bundle.delete.

ダッシュボードのセットアップと完全なCLIの例については、 プレビュー ワークフロー用のアプリ プレビュー キーを使用します.

注

ロール バインディングが付与されていないキーの場合、モードベースのシステムにフォールバックします (read, upload, write, all組織の作成権限

権限

API キーを使用して組織を作成する場合、明示的なグローバル権限を使用します。 org.create.

この権限は、通常のorg/appロールバインディングとは別のものです。組織がまだ存在していないため、__CAPGO_KEEP_0__ キーが呼び出されたときに POST /organization/ API キーを使用して組織を作成するには:

• API キーには org.create に global_permissions.
• API キーには現在の組織スコープの org_admin または org_super_admin __CAPGO_KEEP_0__ キーには、組織スコープの
• New API keys do not receive org.create 新しい__CAPGO_KEEP_0__ キーには、デフォルトでは __CAPGO_KEEP_0__ キーを有効にすることで、組織を作成できます。 RBAC API キーを作成または編集するとき
• 既存の書き込み可能な組織管理者/管理者 API キーは、既存の統合が組織を作成し続けるようにバックフィルされました。 org.create 既存の統合が組織を作成し続けるようにするため、__CAPGO_KEEP_0__ キーが組織を作成すると、__CAPGO_KEEP_1__ は自動的に同じ __CAPGO_KEEP_2__ キーを新しい組織に割り当てます。

When an API key creates an organization, Capgo automatically assigns that same API key as org_super_admin __CAPGO_KEEP_0__ キーを __CAPGO_KEEP_1__ 統合を通じて作成する場合、組織管理者バインディングとともに __CAPGO_KEEP_2__ キーを含めるようにしてください。

If you create an API key through the API, include global_permissions 組織を作成する場合にのみ適用されます。組織を削除するには、通常、ターゲット組織に削除権限が必要です。

{
  "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.

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

セキュア (ハッシュ) キー

• APIキー 生成後は取得できません。 生成後は取得できません。
• キー再生成は新しいAPIキーを生成し、保存されているハッシュを更新します。
• 生データのAPIキーは本番環境での推奨ではありません。

組織ポリシーにより、ハッシュ化されたAPIキーが強制されます。 enforce_hashed_api_keys 有効期限

有効期限

組織ポリシーでは、有効期限の強制が可能です。

有効期限の強制

• 有効期限の強制 (require_apikey_expiration) — All new keys must have an expiry.
• 最大有効期限 (max_apikey_expiration_days) — The expiry cannot be further than N days from now.

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

1. 最小権限の原則: 最も制限の厳しいロールを割り当て、機能するようにするために必要な限り
2. 定期的なローテーション: API キーを定期的に再生成機能を使用してローテーションする
3. 安全なストレージ: API キーを安全に保存し、バージョン管理にコミットしない
4. ハッシュ化されたキーを使用安全な(ハッシュ化された)キーを作成して、生産環境の統合に使用します。
5. 期限設定キーを使用する場合には、常に期限を設定してください。
6. スコープ制限キーを特定のアプリに制限し、必要なロールを最小限に抑えてください。

一般的な使用例

1. CI/CD統合または app_uploader CI/CD統合用にキーを特定のアプリに制限します。 app_developer ロール、そして期限を設定します。
2. PRプレビュー チャンネル: 使用 app_preview CI がバンドルをアップロードするためにプレビュー アプリまたはアプリを使用する場合、または一時的なチャネルを作成し、チャネルとバンドルを一時的にクリーンアップする必要がある場合にのみ使用してください。
3. デプロイメント オートメーション: 自動化されたデプロイ スクリプト用に役割付きのキーを使用してください。 app_developer モニタリング ツール
4. : 外部モニタリング統合用に役割付きのキーを作成してください。管理者アクセス app_reader : 管理者ツール用に役割付きのキーを慎重に使用してください。
5. サード パーティ インテグレーションrole org_admin Deployment Automation
6. Monitoring Tools: アプリに特定のロールを持つ最小限のキーで制限されたキーを作成します。
7. 組織プロビジョニング: 特定のアプリに制限されたキーを作成するための最小限のロールを持つキー。 org_admin または org_super_admin アプリフロー org.create アプリフロー

Keep going from API Keys

アプリフロー API Keys アプリフロー @capgo/capacitor-social-login Capgoの実装詳細については@capgo/capacitor-social-loginを参照してください。 @capgo/capacitor-passkey Capgoの実装詳細については@capgo/capacitor-passkeyを参照してください。 @capgo/capacitor-native-biometric Capgoの実装詳細については@capgo/capacitor-native-biometricを参照してください。 2要素認証 2要素認証の実装詳細については、 SSO (エンタープライズ) Capgoの実装詳細についてはSSO (エンタープライズ)を参照してください。