[API キー]

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

API キーを使用する

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

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

一部のエンドポイントでは、専用のキー ヘッダーも受け入れられます。 チャンネル API 受け入れる authorization または capgkeyチャンネルを選択してください。自動化のプレビュー用に、そのうちの 1 つを使用してください。

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 プレビュー キーをプレビュー ワークフローに使用します.

注記

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

Organization creation permission

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

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

• API キーには org.create __CAPGO_KEEP_0__ キーには global_permissions.
• The same API key must also have a current organization-scoped org_admin __CAPGO_KEEP_0__ キーには org_super_admin __CAPGO_KEEP_0__ キーには
• API キーには 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__ から作成する場合、組織管理者バインディングとともに含めてください。

If you create an API key through the API, include global_permissions 組織の削除には、削除権限が必要です。通常、__CAPGO_KEEP_0__ キーは、セキュア (ハッシュ) キーを使用して削除します。

{
  "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 有効期限

有効期限

組織ポリシーで強制することができます:

有効期限の強制

• 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.

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

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

CI/CD統合

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

Keep going from API Keys

__CAPGO_KEEP_0__ キーから続けてください API キーを使用して認証とアカウントフローを計画している場合、@API/__CAPGO_KEEP_1__-social-login に接続してください。 __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)の実装詳細については。