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トークンにも受け入れられますが、主に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パーミッション

「RBACパーミッション」セクション

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).
• — オプションのアプリケーションごとのパーミッション（例えば __CAPGO_KEEP_0__ キーが明示的なロールバインディングを持つ場合、 app_admin, app_developer, app_uploader, app_reader).

If an API key has explicit role bindings, only those bindings are functional 許可チェックのために評価されます。キー所有者の個人的な許可はキーに継承されません。

注

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

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

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

• 平文キー 作成後は、復元できません。 平文キー
• 再生成は、新しいプレーンテキストのキー (表示されるのは一度) と、保存されたハッシュを更新します。
• ハッシュされたキーは、生産環境での使用を推奨します。

組織のいくつかでは、ハッシュされたキーを「org policy」経由で強制しています。 enforce_hashed_api_keys 有効期限

「有効期限」というセクション

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

有効期限の強制

• ） — 新しいすべてのキーには、期限切れになります。 (require_apikey_expiration最大TTL
• ） — 期限切れは、N日以内に今からではないことを意味します。 (max_apikey_expiration_days組織ポリシーは、以下を強制できます:

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

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

一般的な使用例

1. CI/CD統合:特定のアプリに制限されたキーを app_uploader または app_developer ロール、期限切れ日を設定して
2. デプロイ自動化:自動デプロイスクリプトで app_developer ロールを使用するキーの使用
3. 監視ツール: __CAPGO_KEEP_0__ を作成する app_reader 外部監視統合のためのロール
4. 管理者アクセス: 管理ツールのためのロールを __CAPGO_KEEP_0__ で使用する org_admin 第三者統合
5. : 最小限のロールで特定のアプリに制限された __CAPGO_KEEP_0__ キーを作成する「__CAPGO_KEEP_0__ キーから続ける」

「API キーから続ける」セクション

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