Skip to content
Capacitor Capgo - Capacitorアプリのライブアップデート Capacitor Capgo

API キー

API keys are used to authenticate requests to the Capgo API. Keys are organization-specific and can be assigned RBAC roles for fine-grained access control. Each key can also have an optional expiration date and can be created as a “secure” (hashed) key where the plain-text value is only shown once.

Using an API key

「API キーを使用する」セクションのタイトル

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

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

一部のエンドポイントでは、専用のキー ヘッダーも受け入れます。 API チャンネル を受け入れます authorization または capgkey; プレビュー チャンネル アウトメモのために、そのヘッダーを使用してください。

RBAC 権限

「RBAC 権限」セクションのタイトル

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

  • 組織ロール 組織全体のキー基本許可を定義します（例えば、 org_admin アプリロール org_member).
  • アプリごとの許可（例えば、 もし__CAPGO_KEEP_0__キーに明示的なロールバインドが設定されている場合、 app_admin, app_developer, app_uploader, app_reader許可チェックの評価にのみ、 app_preview).

If an API key has explicit role bindings, プレビュー チャネル自動化 「プレビュー チャネル自動化」セクション

組織全体のキー基本許可を定義します（例えば、

アプリごとの許可（例えば、

CI用のプレビューアプリにのみ、臨時で非公開のプレビュー チャネルを作成し、バンドルをアップロードし、プロモートし、両方を削除するアプリケーションにのみバインドする。 app_preview クリップボードにコピー

{
  "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 __CAPGO_KEEP_0__のアプリレコードの内部UUIDです。__CAPGO_KEEP_0__のコマンド (例えば、) によって使用されるパブリック アプリ識別子とは異なります。 app_id is the app record’s internal UUID, not the public app identifier used by CLI commands (for example, 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は、各バンドルをアップロードしたApp Previewキーを記録します。キーは、各プレビュー チャンネルでのみ自分のバンドルをアップグレードできます。既存のデフォルト/メインチャンネル、別のプレビュー キーによって作成されたチャンネル、または別のキーによって作成されたバンドルのチャンネルライフサイクルアクセスはありません。このワークフローでは、 public と使用しないでください。 --default.

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

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

RBAC API キーの権限の説明図

組織の作成権限

組織の作成権限

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

この権限は、通常のorg/appロールバインディングとは別です。組織がまだ存在していないためです。 POST /organization/ 組織を作成するには、API キーを使用する場合、以下の条件を満たす必要があります:

  • API キーには org.create に含まれている必要があります。 global_permissions.
  • The same API key must also have a current organization-scoped org_admin または org_super_admin バインディング。
  • 新しい API キーはデフォルトで org.create を取得しません。有効にする 組織を作成する RBAC API キーをダッシュボードで作成または編集する際に
  • 既存の書き込み可能なオーガナイゼーション管理者/スーパーアドミン API キーは org.create でバックフィルされました

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.

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

「セキュア (ハッシュ) キー」のセクション

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

  • 平文キー 作成後は取得できません。 再生成は、新しい平文キー (一度だけ表示) と保存されているハッシュを更新します。
  • ハッシュ キーは、実稼動環境での推奨事項です。
  • 一部の組織では、ハッシュ キーを組織の設定で強制することができます。

__CAPGO_KEEP_0__ enforce_hashed_api_keys 組織ポリシー。

__CAPGO_KEEP_0__

期限

キーは期限付きにすることができます。期限切れのキーは、許可チェックレイヤーで拒否されます。

組織ポリシーは、以下を強制できます:

  • 期限付きキーを必須にする (require_apikey_expiration) — 新しいすべてのキーは期限付きでなければなりません。
  • 最大TTL (max_apikey_expiration_days) — 期限は今からN日以内にはなりません。

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

セクション「セキュリティのベストプラクティス」
  1. 最小権限の原則: __CAPGO_KEEP_0__を使用する最小限の権限で、機能するようにする
  2. 定期的なローテーション: API キーを定期的にローテーションするには、再生成機能を使用してください
  3. セキュア ストレージ: API キーをセキュアに保存し、バージョン管理にコミットしないでください
  4. ハッシュ キーを使用: 生産環境の統合用に安全な(ハッシュ化された)キーを作成してください
  5. 有効期限の設定: 一時的なアクセスやCI/CDアクセス用のキーには、常に有効期限を設定してください
  6. スコープ制限: 最小限の権限で、特定のアプリにキーを制限してください

一般的な使用例

一般的な使用例
  1. CI/CD統合: アプリごとにスコープを設定したキーを作成し、有効期限を設定します。 app_uploader プルリクエストプレビュー チャンネル app_developer : CIがバンドルをアップロードする必要がある場合、プレビュー アプリまたはアプリのみに使用し、臨時チャンネルを作成し、チャンネルとバンドルを自動的にクリーンアップします。
  2. デプロイ自動化: 自動デプロイ スクリプト用にロールが付与されたキーを使用します。 app_preview 監視ツール
  3. __CAPGO_KEEP_0____CAPGO_KEEP_0__ app_developer __CAPGO_KEEP_0__
  4. __CAPGO_KEEP_0__: __CAPGO_KEEP_0__ を使用して外部監視統合にキーを作成します。 app_reader 管理者アクセス
  5. : __CAPGO_KEEP_0__ を使用して、管理ツールにキーを作成します。サードパーティ統合 org_admin : __CAPGO_KEEP_0__ を使用して、特定のアプリに制限されたキーを作成します。
  6. 組織プロビジョニング: __CAPGO_KEEP_0__ を使用して、組織を作成する必要がある信頼できるオートメーションに RBAC キーを使用します。
  7. Admin Access: __CAPGO_KEEP_0__ を使用して外部監視統合にキーを作成します。 org_admin Third-Party Integrations org_super_admin : __CAPGO_KEEP_0__ を使用して、特定のアプリに制限されたキーを作成します。 org.create Organization Provisioning

API キーから続けて

セクションのタイトルは “API キーから続けて”

あなたが「__CAPGO_KEEP_0__ キーから続けて」を使用している場合 「API キーから続けて」 認証とアカウントフローの計画に使用し、__CAPGO_KEEP_0__ キーから続けてを「@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-social-login」に接続する 「@capgo/capacitor-social-login」に取り組む実装の詳細は「@capgo/capacitor-social-login」 「@capgo/capacitor-passkey」に取り組む実装の詳細は「@capgo/capacitor-passkey」 「@capgo/capacitor-native-biometric」に取り組む実装の詳細は「@capgo/capacitor-native-biometric」 for the implementation detail in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric for the implementation detail in @capgo/capacitor-native-biometric, __CAPGO_KEEP_3__は保護されたトークンなので、Capgoのドキュメントで使用されているものと同じです。 2要素認証の実装詳細について SSO (エンタープライズ)の実装詳細について ページを編集