API Keys

インストールステップと完全なマークダウンガイドを含むセットアップの質問をコピーする。

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

API キーを使用する

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

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

一部のエンドポイントでは、特定のキーヘッダーも受け入れられます。 API チャンネル __CAPGO_KEEP_0__ チャンネル authorization または、プレビューチャンネル自動化のために、そのいずれかのヘッダーを使用してください。 capgkeyRBAC 権限

「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_0__ キーに存在する場合、 app_admin, app_developer, app_uploader, app_readerkeyの 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 は、アプリレコードの内部 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_KEEP_0__は、各バンドルをアップロードしたApp Preview キーを記録します。キーは、自分が作成したプレビューチャネルにのみ自分のバンドルを昇格させることができます。既存のデフォルト/メインチャネル、別のプレビューキーによって作成されたチャネル、または別のキーのバンドルに対しては、チャネルライフサイクルアクセスはありません。このワークフローでは

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.

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

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

). これらのモードは廃止されています — RBAC ロールを使用してください。

Creating organizations with an API key now uses an explicit global permission: org.create.

This permission is separate from normal org/app role bindings because a new organization does not exist yet when POST /organization/ is called. To create organizations with an API key:

To create organizations with an API key: org.create __CAPGO_KEEP_0__ キーを使用して組織を作成するには global_permissions.
The API key must include org_admin __CAPGO_KEEP_0__ キーには org_super_admin in
New API keys do not receive org.create The same __CAPGO_KEEP_0__ key must also have a current organization-scoped または when creating or editing an RBAC API key in the dashboard.
Existing write-capable org admin/super admin API keys were backfilled with org.create 既存の統合が組織を作成し続けることができるようにする。

キーAPIが組織を作成すると、Capgoはその同じキーAPIを自動的に組織に割り当てる。 org_super_admin 新しく作成された組織にキー__CAPGO_KEEP_2__を割り当てることで、統合は作成した組織を管理できるようになる。組織管理者への手動のロールバインディングが必要なくなる。

組織を作成する際にAPIキーをAPI経由で作成した場合、 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 有効期限

「有効期限」セクション

組織ポリシーで強制することができるものは次のとおりです。

有効期限の強制

有効期限の強制 — すべての新しいキーには有効期限が必要です。 (require_apikey_expiration最大TTL
最大有効期限 (max_apikey_expiration_days — 最近 N 日以内の期限は設定できません。

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

最小権限の原則: 最小限の権限を持つロールを割り当てて、機能するようにしてください
定期的なローテーション: API キーを定期的に再生成機能を使用してローテーションしてください
安全なストレージ: API キーを安全に保管し、バージョン管理にコミットしないでください
ハッシュ化されたキーを使用: 生産環境の統合用に安全な(ハッシュ化された)キーを作成してください
期限の設定: __CAPGO_KEEP_0__を使用するキーの有効期限を常に設定する
Scope Restrictions: __CAPGO_KEEP_0__を特定のアプリに制限し、必要なロールを最小限に抑える

Common Use Cases

CI/CD Integration: 特定のアプリに__CAPGO_KEEP_0__をスコープし、ロールと有効期限を設定する app_uploader or app_developer PR Preview Channels
: CIがバンドルをアップロードし、臨時チャンネルを作成し、自身のチャンネルとバンドルを原子的に消去する必要がある場合にのみ、__CAPGO_KEEP_0__をプレビュー用アプリまたはアプリに使用するrole, app_preview and set an expiration date.
展開自動化__CAPGO_KEEP_0__を使用して、自動展開スクリプトのロールでキーを使用します。 app_developer 監視ツール
__CAPGO_KEEP_0__を使用して、外部監視統合のロールでキーを作成します。管理者アクセス app_reader __CAPGO_KEEP_0__を使用して、管理ツールのロールでキーを使用します。
第三者統合__CAPGO_KEEP_0__を使用して、特定のアプリに制限された最小限のロールでキーを作成します。 org_admin 組織プロビジョニング
__CAPGO_KEEP_0__を使用して、組織のプロビジョニングに必要なロールでキーを作成します。__CAPGO_KEEP_0__を使用して、自動展開スクリプトのロールでキーを使用します。
__CAPGO_KEEP_0__を使用して、外部監視統合のロールでキーを作成します。: 使用する org_admin または org_super_admin RBAC キーを使用して org.create 信頼できるオートメーションにのみ組織を作成する必要がある場合にのみ。

API キーから続けてください。

Capgo を使用している場合 API キー 認証とアカウントフローの計画に使用する場合、@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-social-login に接続します。 @capgo/capacitor-social-login の実装詳細については、@capgo/capacitor-social-login を参照してください。 @capgo/capacitor-passkey @capgo/capacitor-passkey 実装詳細のために@capgo/capacitor-passkeyの @capgo/capacitor-native-biometric 実装詳細のために@capgo/capacitor-native-biometricの 2要素認証実装詳細のために2要素認証、 SSO (企業) ページを編集する