API キー

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

使用する API キー

API キーをパスワードとしてパスワードのヘッダーに含めます。 x-api-key リクエストのヘッダーに__CAPGO_KEEP_0__ キーを含めてください。

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

ヘッダーは、JWTトークンにのみ使用することを意図しています。UUID形式の__CAPGO_KEEP_0__ キーを使用すると機能しますが、すべてのキータイプ (安全/ハッシュされたキーを含む) に対して推奨されるヘッダーです。 authorization header is also accepted but is primarily intended for JWT tokens. When the value is a UUID-formatted API key it works, but x-api-key セクション「RBAC権限」

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

API keys use the same role-based access control (RBAC) system as user accounts. When creating or managing keys through the web app, you assign roles at two levels:

• 組織ロール — 組織全体の基準許可を定義するキーのキー (例えば org_admin, org_member).
• アプリロール — オプションのアプリごとの許可 (例えば app_admin, app_developer, app_uploader, app_reader).

API キーが明示的なロールのバインドを持つ場合、 明示的なロールのバインド のみが許可チェックの評価対象となります。キーオーナーの個人的な許可はキーよりも継承されません。

注

ロールのバインドがなければ、モードベースのシステムにフォールバックします (read, upload, write, all). これらのモードは廃止されたものです — RBAC ロールを使用してください。

組織作成許可

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

この許可は、通常のorg/appロールバインディングとは別のものです。組織がまだ存在していないためです。 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__ キーを有効にする必要があります。
• Enable API key to receive org.create The same __CAPGO_KEEP_0__ key must also have a current organization-scoped binding or 組織を作成することを許可する ダッシュボードでRBAC API キーを作成または編集するときに
• 既存の書き込み可能な組織管理者/管理者 API キーは 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.

組織を作成する場合にのみ適用されます。組織を削除するには、通常はターゲット組織に削除権限が必要です。

作成時に安全なキーを作成する場合、サーバーはキー材料を生成し、平文値を一度だけ返します。ハッシュのみが保存されます。このことは次のことを意味します:

• __CAPGO_KEEP_0__ 平文キー は作成後
• 取得できません。
• 再生成は、新しい平文キー (1 回表示) と保存されているハッシュを更新します。

ハッシュ キーは、生産環境での推奨事項です。 enforce_hashed_api_keys 組織のいくつかでは、組織ポリシーを通じてハッシュ キーを強制しています。

有効期限

キーには、有効期限がオプションで指定できます。期限切れのキーは、許可チェック層で拒否されます。

組織ポリシーでは、次のことが強制されます:

• 強制期限 (require_apikey_expiration) — 新しいすべてのキーには期限が必要です。
• 最大TTL (max_apikey_expiration_days) — 期限は今からN日以内に設定する必要があります。

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

1. 最小権限の原則: インテグレーションが機能する限り、最も制限的なロールを割り当てます。
2. 定期的なローテーション: API キーを定期的に再生成する機能を使用してキーをローテーションします。
3. 安全なストレージ: API キーを安全に保存し、バージョン管理にコミットしないでください。
4. ハッシュされたキーを使用: 生産環境統合用に安全な(ハッシュ化された)キーを作成
5. 有効期限の設定: 一時的なアクセスやCI/CDアクセス用のキーに常に有効期限を設定
6. スコープ制限: 最小限の必要なロールと共に特定のアプリに制限する

共通の使用例

1. CI/CD統合: 特定のアプリにスコープを設定し、ロールと共に有効期限を設定 app_uploader または app_developer ロール
2. 展開自動化: __CAPGO_KEEP_0__ キーを使用して app_developer 自動展開スクリプトのロール
3. 監視ツール: __CAPGO_KEEP_0__ キーを使用して app_reader 外部監視統合のロール
4. 管理者アクセス: __CAPGO_KEEP_0__ キーを使用して org_admin 管理ツールのロールに控えめに
5. 第三者統合: __CAPGO_KEEP_0__ キーを制限して
6. 特定のアプリに必要なロールで最小限に抑えた場合に使用する: __CAPGO_KEEP_0__ を使用します。 org_admin または org_super_admin RBAC キーを使用して、信頼できるオートメーションにのみ組織を作成する必要がある場合 org.create __CAPGO_KEEP_0__ キーから続けてください。

セクションのタイトル “API キーから続けてください。”

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