API キー

API キーは、Capgo API へのリクエストを認証するために使用されます。各キーには、アクセスレベルを制御するための異なる権限 (モード) を設定できます。キーは組織固有であり、Capgo リソースへのアクセスを許可するため、慎重に管理する必要があります。

キーモード

読み取り: データの読み取りのみが可能で、変更は許可されません
アップロード: 新しいバンドルの読み取り、変更、アップロードが可能
書き込み: データの読み取り、変更、バンドルのアップロードが可能
all: すべての操作へのフルアクセス

キーモードは、段階的/段階的なスキーマに従います。アップロードキーを持っていて、書き込みキーを作成すると、書き込みキーはアップロードキーで実行できるすべてのことを実行できるようになります。 API キーがどのように機能するかをよりよく理解するには、次の図をご覧ください。

権限が制限されたサブキー

特定のアプリまたは組織へのアクセスが制限されたサブキーを作成できます。これは、特定のリソースへのアクセスを制限しながら、他のリソースに対する操作を許可する場合に便利です。これらの制限を定義するには、キーを作成するときに limited_to_apps および limited_to_orgs パラメーターを使用します。

暗号化されたキー

セキュリティを強化するために、暗号化された (ハッシュ化された) API キーを作成できます。暗号化キーを作成する場合:

キーはデータベースに保存される前に SHA-256 を使用してハッシュされます。
プレーンキーは作成応答で 1 回だけ返されます - すぐに保存します
作成後にキーを再度取得したり表示したりすることはできません
暗号化されたキーを紛失した場合は、新しいキーを作成する必要があります

暗号化を有効にするキーを作成する場合は、hashed: true パラメーターを使用します。これは実稼働環境に推奨されるアプローチです。

キーの有効期限

API キーには 有効期限 を設定して、キーが侵害された場合の危険範囲を制限できます。有効期限が設定されている場合:

指定した日時を過ぎるとキーが機能しなくなります
期限切れのキーを使用したリクエストはエラーで拒否されます。
期限切れのキーは 30 日後に自動的にクリーンアップされます

組織は有効期限ポリシーを適用できます。

有効期限が必要: すべての API キーには有効期限が必要です
最大有効期限: 有効期限を設定できる将来の期間を制限します。

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

最小特権の原則: 統合が機能できる最も制限的なモードを常に使用します。
暗号化キーを使用: 運用環境用にハッシュされたキーを作成し、データベース侵害から保護します
有効期限の設定: 有効期限を使用してキーの有効期間を制限します。
定期的なローテーション: API キーを定期的にローテーションします。
安全なストレージ: API キーを安全に保存し、バージョン管理にコミットしないでください。
監視: API キーの使用状況を監視し、漏洩したキーを直ちに取り消します。
制限されたサブキー: リスクを最小限に抑えるために、特定の統合に対して制限された権限を持つサブキーを使用します。

エンドポイント

入手

https://api.capgo.app/apikey/

アカウントに関連付けられているすべての API キーを取得します。

応答タイプ

interface ApiKey {
  created_at: string | null
  id: number
  key: string | null  // null for encrypted keys
  mode: 'read' | 'write' | 'upload' | 'all'
  name: string
  updated_at: string | null
  user_id: string
  limited_to_apps?: string[]
  limited_to_orgs?: string[]
  expires_at?: string | null  // ISO 8601 date, null means never expires
}
```> **注意**: 暗号化キーの場合、プレーンキーは作成中に 1 回しか表示されないため、GET 応答の `key` フィールドは `null` になります。

#### リクエストの例

```bash
curl -H "authorization: your-api-key" https://api.capgo.app/apikey/

応答例

{
  "data": [
    {
      "id": 1,
      "key": "ak_123...",
      "mode": "read",
      "name": "CI/CD Read Key",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "user_id": "user_123"
    },
    {
      "id": 2,
      "key": "ak_456...",
      "mode": "upload",
      "name": "Deploy Bot",
      "created_at": "2024-01-02T00:00:00Z",
      "updated_at": "2024-01-02T00:00:00Z",
      "user_id": "user_123",
      "limited_to_apps": ["com.demo.app"]
    }
  ]
}

投稿

https://api.capgo.app/apikey/

特定の組織に新しい API キーを作成します。

リクエスト本文

interface ApiKeyCreate {
  name: string
  mode: 'read' | 'write' | 'upload' | 'all'
  limited_to_apps?: string[]
  limited_to_orgs?: string[]
  hashed?: boolean       // Create an encrypted key (recommended for production)
  expires_at?: string    // ISO 8601 date for key expiration
}

リクエストの例 (標準キー)

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Limited Read Key",
    "mode": "read",
    "limited_to_apps": ["com.demo.app"]
  }' \
  https://api.capgo.app/apikey/

リクエストの例 (有効期限のある暗号化キー)

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Secure CI Key",
    "mode": "upload",
    "hashed": true,
    "expires_at": "2025-06-01T00:00:00Z"
  }' \
  https://api.capgo.app/apikey/

応答例 (標準キー)

{
  "apikey": {
    "id": 3,
    "key": "ak_789...",
    "mode": "read",
    "name": "Limited Read Key",
    "created_at": "2024-02-12T00:00:00Z",
    "user_id": "user_123",
    "limited_to_apps": ["com.demo.app"]
  }
}

応答例 (暗号化キー)

{
  "apikey": {
    "id": 4,
    "key": "ak_abc123...",
    "mode": "upload",
    "name": "Secure CI Key",
    "created_at": "2024-02-12T00:00:00Z",
    "user_id": "user_123",
    "expires_at": "2025-06-01T00:00:00Z"
  }
}

重要: 暗号化キーの場合、この応答の key 値は、プレーンキーが表示される唯一のです。すぐに安全な場所に保存してください。後続の GET リクエストは、key フィールドに対して null を返します。

削除

https://api.capgo.app/apikey/:id/

既存の API キーを削除します。これを使用して、アクセスをすぐに取り消します。

パラメータ

id: 削除する API キーの ID (キー文字列自体ではなく数値識別子)

リクエストの例

curl -X DELETE -H "authorization: your-api-key" https://api.capgo.app/apikey/1/

成功の応答

{
  "success": true
}

一般的な使用例

CI/CD 統合: CI パイプラインの読み取り専用キーを作成して、展開ステータスを確認します
展開の自動化: 自動展開スクリプトにアップロードモードキーを使用します。
監視ツール: 外部監視統合に読み取りモードキーを使用します。
管理者アクセス: 管理ツールにはすべてのモードキーを慎重に使用してください
制限付きアクセス: サードパーティ統合用に、特定のアプリまたは組織に対する制限された権限を持つサブキーを作成します

エラー処理

一般的なエラーのシナリオとその対応:

// Invalid mode
{
  "error": "Invalid mode specified. Must be one of: read, write, upload, all",
  "status": "KO"
}

// Key not found
{
  "error": "API key not found",
  "status": "KO"
}

// Permission denied
{
  "error": "Insufficient permissions to manage API keys",
  "status": "KO"
}

// Expired API key used for authentication
{
  "error": "API key has expired",
  "status": "KO"
}

// Invalid expiration date (in the past)
{
  "error": "Expiration date must be in the future",
  "status": "KO"
}

// Organization requires expiration
{
  "error": "Organization policy requires an expiration date for API keys",
  "status": "KO"
}

// Expiration exceeds organization limit
{
  "error": "Expiration date exceeds organization maximum of 90 days",
  "status": "KO"
}