API キー

インストール

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

APIキーを使用する

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

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

一部のエンドポイントでは、専用のキーヘッダーも受け入れられます。チャンネル API 受け入れる authorization または capgkeyチャンネルを選択してください。

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 がアップロードした各バンドルを記録するアプリプレビューキーです。キーは、自身のバンドルを各プレビューチャネルにアップグレードできます。ただし、既存のデフォルト / メインチャネル、別のプレビューキーによって作成されたチャネル、または別のキーのバンドルのチャネルライフサイクルアクセスはありません。このワークフローでは、 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 __CAPGO_KEEP_0__ キーには現在の組織スコープの
New API keys do not receive org.create __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__ キー

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.

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

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

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

組織ポリシーを通じて、ハッシュされたキーを強制する組織もあります。 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.

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

最小権限の原則: __CAPGO_KEEP_0__ の最小限の権限を付与する必要があります。
定期的なローテーション: API のキーを定期的にローテーションするために、再生成機能を使用してください。
安全なストレージ: API のキーを安全に保存し、バージョン管理に含めることは絶対にしないでください。
ハッシュ化されたキーを使用安全な(ハッシュ化された)キーを作成して、生産環境の統合に使用します。
期限設定キーを使用する場合には、常に期限を設定してください。
スコープ制限キーを特定のアプリに制限し、必要なロールを最小限に抑えてください。

一般的な使用例

CI/CD統合または app_uploader アプリのスコープとロールを指定し、期限を設定してください。 app_developer PRプレビューチャンネル
PRプレビューチャンネル: 使用 app_preview CI がバンドルをアップロードするためにプレビューアプリまたはアプリにのみ使用し、臨時チャンネルを作成し、自身のチャンネルとバンドルを原子的にクリーンアップする必要がある場合。
デプロイメントオートメーション: 自動化されたデプロイスクリプト用に役割付きのキーを使用します。 app_developer モニタリングツール
: 外部モニタリング統合用に役割付きのキーを作成します。管理者アクセス app_reader : 管理者ツール用に役割付きのキーをsparingly使用します。
サードパーティインテグレーションrole org_admin Deployment Automation
Monitoring Tools:
Organization Provisioning: org_admin または org_super_admin Capacitorライブアップデートの代替手段を比較するページ。ロール：長いマーケティングまたは法的文章。見つける場所：ページalternatives.astro。Capgo製品/ブランドと開発者用語を完全に保持する。 org.create Appflowの比較/移行マーケティングコピー。ロール：長いマーケティングまたは法的文章。見つける場所：ページionic-appflow.astro、ページionic-enterprise-plugins.astro、ページsolutions/ionic-enterprise-plugins.astro。Capgo製品/ブランドと開発者用語を完全に保持する。

Keep going from API Keys

Appflowの比較/移行マーケティングコピー。ロール：短いUIラベルまたはナビゲーションアイテム。見つける場所：ページionic-appflow.astro、ページionic-enterprise-plugins.astro、ページsolutions/ionic-enterprise-plugins.astro。 API Keys RBACキーと @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)の実装詳細については。