メインコンテンツへスキップ
Capgo - Capacitor アプリのビルド、リリース、アップデート Capgo

API キー

API キーは、Capgo API へのリクエストを認証するために使用されます。キーは組織ごとに管理され、RBACロールを割り当てることで詳細なアクセス制御が可能です。また、各キーには有効期限を設定できるほか、プレーンテキストの値が一度しか表示されない「セキュア（ハッシュ化）」キーとして作成することもできます。

API key の使用方法

「API key の使用方法」というセクション

各エンドポイントのドキュメントに従って認証ヘッダーを使用してください。API key を使用したリクエストでは、 authorization 以下が受け入れられます：

ターミナル
curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...

一部のエンドポイントでは、専用のキーヘッダーも使用可能です。 API チャンネル は以下をサポートしています： authorization または capgkey；preview-channel の自動化には、これらのヘッダーのいずれかを使用してください。

RBAC 権限

「RBAC権限」セクション

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

  • 組織ロール — 組織全体におけるキーの基本権限を定義します（例： org_admin または org_member).
  • アプリロール — アプリごとの権限を定義します（例： app_admin, app_developer, app_uploader, app_reader、または app_preview).

もし API キーに明示的なロールの紐付けがある場合、 権限チェックではその紐付けのみが 評価されます。キーの所有者の個人権限は、キーに継承されません。

プレビューチャネルの自動化

「Preview channel automation」セクション

Bind app_preview CI用のプレビューアプリにのみ紐付けます。これにより、一時的な非公開のpreview channelを作成し、bundleをuploadおよびpromoteした後、両方を削除します。

{
  "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）とは異なります。このbindingは、キーに組織全体のロールが付与されていない場合でも、組織に紐付けられた状態を維持します。

アプリレベルの app_preview roleには以下のみが含まれます： app.read, app.read_bundles, app.upload_bundleや app.create_channel。そのキーがchannelを作成すると、Capgo は自動的に channel_preview を新しく作成されたchannelにbindingします。この子bindingによって、 channel.read, channel.promote_bundleや channel.delete そのキーが作成されたチャンネルのみに適用されます。

app_preview を保持します app.read、そのため厳密なチャンネル読み取りの分離ではありません。選択されたアプリ内のチャンネルメタデータを列挙できる可能性があります。自動的な子バインディングにより、 ライフサイクル変更 が、そのキーが作成したチャンネルのみに制限されます。

Capgo は、各bundleをuploadしたApp Previewキーを記録します。このキーは、自身が作成した各プレビューチャンネルに対して、自身のbundleのみをpromoteできます。既存のデフォルト/メインチャンネル、他のプレビューキーによって作成されたチャンネル、または他のキーのbundleに対するチャンネルライフサイクルへのアクセス権はありません。このワークフローでは、 public を省略し、 --default.

使用する channel delete <preview-channel> <public-app-id> --delete-bundle をクリーンアップには決して使用しないでください。これはアトミックで所有権チェックが行われるプレビュークリーンアップルートです。呼び出し元のキーのプレビューチャンネルと、それに関連付けられたbundleのみを削除します。 app_preview は、一般的な bundle.delete.

ダッシュボードの設定と完全な CLI の例については、以下を参照してください。 プレビューワークフローにはApp Previewキーを使用してください.

RBACによるAPIキーの権限管理の仕組みを示す図

Organization作成権限

「Organization作成権限」セクション

APIキーを使用してOrganizationを作成する場合、現在は明示的なグローバル権限を使用します： org.create.

この権限は通常のorg/appロールの紐付けとは異なります。なぜなら、呼び出し時に新しいorganizationが POST /organization/ まだ存在しないためです。APIキーでOrganizationを作成するには：

  • APIキーに以下を含める必要があります org.create における global_permissions.
  • 同じ API キーには、現在有効な組織スコープの org_admin または org_super_admin バインディングも必要です。
  • 新しい API キーには、デフォルトでは org.create 付与されません。有効にするには、 「組織の作成を許可する」を ダッシュボードで RBAC API キーを作成または編集する際にオンにしてください。
  • 既存の書き込み可能な組織管理者/スーパー管理者の API キーには、 org.create 既存のインテグレーションが引き続き組織を作成できるよう、権限がバックフィルされました。

API キーが組織を作成すると、Capgo は自動的にその同じ API キーを org_super_admin 新しく作成された組織に割り当てます。これにより、インテグレーションは別途手動でロールをバインドすることなく、作成したばかりの組織を管理できるようになります。

API を通じて API キーを作成する場合、以下を含める必要があります： global_permissions 組織管理者（org admin）のバインディングと併せて：

{
  "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.

セキュア（ハッシュ化）キー

「Secure (Hashed) Keys」セクション

Secure key を作成する際、サーバーはキーの素材を生成し、プレーンテキストの値を一度だけ返します。保存されるのはハッシュ値のみです。つまり：

  • プレーンテキストのキーは 取得できません 作成後は不可となります。
  • 再生成（Regeneration）を行うと、新しいプレーンテキストのキー（一度のみ表示）が生成され、保存されているハッシュが更新されます。
  • 本番環境では Hashed keys の使用を推奨します。

一部の組織では、ハッシュ化キーの使用を 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 連携: Create keys scoped to specific apps with the app_uploader または app_developer 有効期限を設定します。
  2. PR Preview Channels: 使用する app_preview : CI が bundle を upload し、一時的な channel を作成し、自身の channel と bundle をアトミックにクリーンアップする必要がある場合、プレビューアプリのみに限定して使用します。
  3. デプロイの自動化: 自動デプロイ用スクリプトには、 app_developer role のキーを使用します。
  4. モニタリングツール: 外部モニタリング連携用に、 app_reader role を持つキーを作成します。
  5. 管理者アクセス: 管理ツールには、 org_admin role を持つキーを最小限に使用してください。
  6. サードパーティ連携: 最小限の role に制限した、特定のアプリ専用のキーを作成します。
  7. 組織プロビジョニング: 次の org_admin または org_super_admin RBAC key を使用します org.create 組織の作成が必要な、信頼された自動化プロセス専用です。

API Keys から次へ

「API Keys から次へ」というセクション

使用している場合 API キー 認証とアカウントフローを計画するには、これを次と連携させてください @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 (Enterprise) の実装詳細については、