API キー

このプラグインのインストール手順とフルマークダウンガイドを含むセットアッププロンプトをコピーします。

API キーは、Capgo API へのリクエストの認証に使用されます。キーは組織固有のもので、RBACロールを割り当てることで細かいアクセス制御を行うことができます。キーには期限日付が設定できるほか、ハッシュ化されたキー（平文値は1度だけ表示される）として作成することもできます。

API キーを使用する

API キーをCLIに渡します x-api-key すべてのリクエストのヘッダー:

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

この authorization ヘッダーはJWTトークンに主に使用されるため、受け入れられますが、推奨されていません。API キーの値がUUID形式の場合、機能しますが、 x-api-key すべてのキー種類（包括安全/ハッシュされたキー）に対して推奨されるヘッダーです。

RBAC権限

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

組織ロール — 組織全体の基準的な権限を定義します（例えば org_admin, org_member).
アプリロール — オプションのアプリ固有の許可 (例えば app_admin, app_developer, app_uploader, app_reader).

もし API キーに明示的なロールのバインディングが含まれている場合、 そのバインディング のみ許可のチェックのために評価されます。キー所有者の個人的な許可はキーに継承されません。

組織の作成許可

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 組織を作成する許可を付与するには、RBAC __CAPGO_KEEP_0__ キーを作成または編集するときにダッシュボードで を有効にする必要があります。 既存の書き込み可能なorg admin/super admin API キーはバックフィルされました。
Existing write-capable org admin/super admin API keys were backfilled with org.create 組織がすでに存在する場合は、組織を作成することができます。

API キーが組織を作成すると、Capgo はその同じ API キーを自動的に組織に割り当てます。 org_super_admin 新しく作成された組織に割り当てられるため、インテグレーションは新しく作成した組織を管理することができます。組織を作成した後、別の手動のロールバインディングが必要ありません。

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.

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

平文キーキー

取得できません cannot be retrieved __CAPGO_KEEP_0__.
再生成は、表示される新しいテキストキーと、保存されたハッシュを更新します。
生のキーは、実稼働環境での推奨事項です。

組織がハッシュされたキーを強制する場合があります。 enforce_hashed_api_keys 有効期限

「有効期限」セクション

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

有効期限の強制

— 新しいすべてのキーには、期限切れのキーが許可チェック層で拒否されるオプションの有効期限が設定されます。 (require_apikey_expiration最大TTL
__CAPGO_KEEP_1__ (max_apikey_expiration_days — __CAPGO_KEEP_0__ は N 日以内に到来することはできません。

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

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

一般的な使用例

CI/CD統合: __CAPGO_KEEP_0__を使用するキーに特定のアプリに制限し、ロール、期限を設定してください。 app_uploader デプロイ自動化 app_developer : __CAPGO_KEEP_0__を使用するキーにロールを設定して、自動化されたデプロイスクリプトで使用してください。
セクション: __CAPGO_KEEP_1__ app_developer role for automated deployment scripts
監視ツール: __CAPGO_KEEP_0__でキーを作成して app_reader 外部監視統合のためのロール
管理者アクセス: __CAPGO_KEEP_0__でキーを作成して org_admin 管理者ツールのためのロールを慎重に使用して
第三者統合: __CAPGO_KEEP_0__でキーを制限して特定のアプリに制限する必要のあるロール
組織プロビジョニング: __CAPGO_KEEP_0__またはRBACキーを使用して org_admin or 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-native-biometricの実装詳細については、@capgo/capacitor-native-biometricを参照してください @capgo/capacitor-native-biometricの実装詳細については、@capgo/capacitor-native-biometricを参照してください @capgo/capacitor-native-biometricの実装詳細については、@capgo/capacitor-native-biometricを参照してください @capgo/capacitor-native-biometricの実装詳細については、@capgo/capacitor-native-biometricを参照してください 2要素認証 __CAPGO_KEEP_0__、2要素認証の実装詳細について SSO (Enterprise) __CAPGO_KEEP_0__、SSO (Enterprise)の実装詳細について