API キー

このプラグインのインストール手順と全マークダウンガイドを含む設定プロンプトをコピーする

API キーは、Capgo API への要求を認証するために使用されます。キーは組織固有であり、RBAC ロールを割り当てて細かいアクセス制御を行うことができます。各キーには期限切れ日付もオプションで設定でき、セキュア (ハッシュ) キーとして作成することもできます。ハッシュ値は、初回表示後は表示されません。

API キーを使用する

API キーを使用する場合 authorization __CAPGO_KEEP_0__ キーを使用する

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

また、特定のキーヘッダーも受け入れます。チャンネル API 受け入れる authorization または capgkeyチャンネル __CAPGO_KEEP_0__ を使用して、

RBAC 権限

API keys use the same role-based access control (RBAC) system as user accounts. When creating or managing keys through the web app or API, you assign roles at two levels:

組織ロール — 組織全体でキーが持つ基準の権限を定義します (例えば、 org_admin アプリロール org_member).
— アプリごとの権限 (例えば、 __CAPGO_KEEP_1__ 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_KEEP_0__ は各バンドルをアップロードしたアプリプレビューキーを記録します。キーは、各プレビューチャンネルで自分のバンドルをのみ上げることができます。既存のデフォルト / メインチャンネル、別のプレビューキーによって作成されたチャンネル、または別のキーのバンドルのチャンネルライフサイクルアクセスはありません。このワークフローでは、

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の例については、プレビューワークフローでApp プレビューキーを使用する.

権限

API キーを使用して組織を作成する場合、明示的なグローバル許可が使用されます: org.create.

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

API キーには org.create に含まれている必要があります。 global_permissions.
API キーには org_admin も含まれている必要があります。 org_super_admin または
API キーには org.create も含まれている必要があります。 __CAPGO_KEEP_0__ キーには、現在の組織スコープの許可が必要です。 RBAC API キーを作成または編集するとき
ダッシュボード内で既存の書き込み可能な組織管理者/管理者 API キーは、既存の統合が組織を作成し続けるようにバックフィルされました。 org.create 既存の統合が組織を作成し続けるようにするために、__CAPGO_KEEP_0__ キーを作成する際に __CAPGO_KEEP_1__ は、__CAPGO_KEEP_2__ キーを自動的に割り当てます。

API キーが組織を作成すると、Capgo はその組織に同じ API キーを割り当てます。 org_super_admin __CAPGO_KEEP_0__ キーを作成する際に __CAPGO_KEEP_1__ を含めるには、組織管理者バインディングと一緒に含める必要があります。

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.

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

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

平文キー 取得できません 作成後
再生成は、新しい平文キー (1 回表示) と、保存されたハッシュを更新します。
生産環境での使用には、ハッシュされたキーが推奨されます。

組織ポリシーを通じて、ハッシュされたキーを強制する組織もあります。 enforce_hashed_api_keys 有効期限

セクション名 “有効期限”

組織ポリシーで強制できるのは

有効期限の強制

Section titled “Expiration” (require_apikey_expiration) — All new keys must have an expiry.
最大有効期限 (max_apikey_expiration_days) — The expiry cannot be further than N days from now.

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

最小権限の原則: 最も制限の厳しいロールを割り当てることができる限り、
定期的なローテーション: API キーを定期的に API regenerate機能を使用してローテーションする
安全なストレージ: API キーを安全に保存し、バージョン管理にコミットしない
ハッシュ化されたキーを使用する:
生産統合用に安全な(ハッシュ化された)キーを作成します。期限
: 一時またはCI/CDアクセス用に使用するキーに期限を設定することを常に実行します。スコープ制限

: 最小限の必要なロールで特定のアプリにキーを制限します。

セクション「一般的な使用例」CI/CD統合 app_uploader : app_developer または
PRプレビューチャンネル: 使用 app_preview CI がバンドルをアップロードする必要がある場合、または一時的なチャンネルを作成し、チャンネルとバンドルを自動的にクリーンアップする必要がある場合にのみ、プレビューアプリまたはアプリにのみ使用します。
デプロイメントオートメーション: 自動化されたデプロイスクリプト用にロールを付与したキーのみを使用します。 app_developer モニタリングツール
: 外部モニタリング統合用にロールを付与したキーのみを作成します。管理者アクセス app_reader : 管理者ツール用にロールを付与したキーのみを使用します。ただし、慎重に使用してください。
サードパーティインテグレーション__CAPGO_KEEP_0__ org_admin __CAPGO_KEEP_0__
__CAPGO_KEEP_0__: __CAPGO_KEEP_0__ を使用して、特定のアプリに制限されたキーを作成します。
Organization Provisioning: __CAPGO_KEEP_0__ を使用して org_admin または org_super_admin context org.create Capacitorライブアップデートの代替手段を比較するページ。ロール：長いマーケティングまたは法的文章。ページ/エリア：ページalternatives.astro。保管するCapgo製品/ブランドと開発者用語は正確に。メッセージキー：alternatives_cta_questions (代替CTA質問)。

Keep going from API Keys

Appflowの比較/移行マーケティングコピー。ロール：短いUIラベルまたはナビゲーションアイテム。ページ/エリア：ページionic-appflow.astro、ページionic-enterprise-plugins.astro、ページsolutions/ionic-enterprise-plugins.astro。メッセージキー：appflow_plugins_or (Appflowプラグインまたは)。 : API を使用して、RBAC キーを作成します。 : __CAPGO_KEEP_0__ を使用して、信頼できる自動化にのみ組織を作成する必要がある場合にのみ。 @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 (Enterprise) SSO (Enterprise)の実装詳細については。