Docs/keys-api

API Keys API

APIキーの管理を行うAPIです。

エンドポイント一覧

メソッドエンドポイント説明スコープ
GET/api/keysAPIキー一覧の取得read:keys
POST/api/keysAPIキーの作成write:keys
GET/api/keys/{keyId}特定のAPIキーの取得read:keys
PUT/api/keys/{keyId}APIキーの更新write:keys
DELETE/api/keys/{keyId}APIキーの削除write:keys

APIキー一覧の取得

すべてのAPIキーを取得します。

Endpoint: GET /api/keys

必要なスコープ: read:keys

リクエスト例:

curl -X GET https://your-domain.com/api/keys \
  -H "Authorization: Bearer YOUR_API_TOKEN"

レスポンス例:

{
  "success": true,
  "message": "success",
  "data": [
    {
      "id": "key_xxxxx",
      "name": "Production API Key",
      "keyHash": "hash_xxxxx",
      "scopes": ["read:jobs", "write:jobs"],
      "enabled": true,
      "expiresAt": "2026-11-04T00:00:00.000Z",
      "lastUsed": "2025-11-04T09:30:00.000Z",
      "createdAt": "2025-11-01T00:00:00.000Z",
      "userId": "user_xxxxx"
    }
  ]
}

APIキーの作成

新しいAPIキーを作成します。

Endpoint: POST /api/keys

必要なスコープ: write:keys

リクエストボディ:

{
  "name": "Production API Key",
  "scopes": ["read:jobs", "write:jobs", "read:logs"]
}

フィールド説明:

フィールド型必須説明
namestring✓APIキー名
scopesstring[]✓付与するスコープのリスト

利用可能なスコープ:

  • read:jobs - ジョブ情報の取得
  • write:jobs - ジョブの作成・更新・削除・実行
  • read:logs - 実行ログ情報の取得
  • write:logs - 実行ログの作成・削除
  • read:keys - APIキー情報の取得
  • write:keys - APIキーの作成・削除

リクエスト例:

curl -X POST https://your-domain.com/api/keys \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "scopes": ["read:jobs", "write:jobs", "read:logs"]
  }'

レスポンス例:

{
  "success": true,
  "message": "created",
  "data": {
    "apiKey": {
      "id": "key_xxxxx",
      "name": "Production API Key",
      "keyHash": "hash_xxxxx",
      "scopes": ["read:jobs", "write:jobs", "read:logs"],
      "enabled": true,
      "expiresAt": "2026-11-04T00:00:00.000Z",
      "lastUsed": null,
      "createdAt": "2025-11-04T10:00:00.000Z",
      "userId": "user_xxxxx"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

⚠️ 重要: token はこのレスポンスでのみ返されます。必ず安全な場所に保存してください。

特定のAPIキーの取得

指定したIDのAPIキーを取得します。

Endpoint: GET /api/keys/{keyId}

必要なスコープ: read:keys

リクエスト例:

curl -X GET https://your-domain.com/api/keys/key_xxxxx \
  -H "Authorization: Bearer YOUR_API_TOKEN"

レスポンス例:

{
  "success": true,
  "message": "success",
  "data": {
    "id": "key_xxxxx",
    "name": "Production API Key",
    "keyHash": "hash_xxxxx",
    "scopes": ["read:jobs", "write:jobs"],
    "enabled": true,
    "expiresAt": "2026-11-04T00:00:00.000Z",
    "lastUsed": "2025-11-04T09:30:00.000Z",
    "createdAt": "2025-11-01T00:00:00.000Z",
    "userId": "user_xxxxx"
  }
}

APIキーの更新

既存のAPIキーの名前を更新します。

Endpoint: PUT /api/keys/{keyId}

必要なスコープ: write:keys

リクエストボディ:

{
  "name": "Updated API Key",
  "scopes": ["read:jobs", "write:jobs"]
}

フィールド説明:

フィールド型必須説明
namestring✓新しいAPIキー名
scopesstring[]✓既存のスコープ（変更不可）

⚠️ 重要: セキュリティ上の理由により、scopes は変更できません。リクエストには既存のスコープをそのまま含める必要があります。スコープを変更したい場合は、新しいAPIキーを作成して古いキーを削除してください。

リクエスト例:

curl -X PUT https://your-domain.com/api/keys/key_xxxxx \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Production API Key",
    "scopes": ["read:jobs", "write:jobs"]
  }'

レスポンス例:

{
  "success": true,
  "message": "APIキーが更新されました",
  "data": null
}

⚠️ 注意: APIキーの更新では、トークン自体は変更されません。トークンを再生成したい場合は、新しいキーを作成して古いキーを削除してください。

APIキーの削除

指定したAPIキーを削除します。

Endpoint: DELETE /api/keys/{keyId}

必要なスコープ: write:keys

リクエスト例:

curl -X DELETE https://your-domain.com/api/keys/key_xxxxx \
  -H "Authorization: Bearer YOUR_API_TOKEN"

レスポンス例:

{
  "success": true,
  "message": "APIキーが削除されました",
  "data": null
}

APIキーの管理ベストプラクティス

キーのローテーション

定期的にAPIキーを再生成することをお勧めします：

  1. 新しいAPIキーを作成
  2. アプリケーションを新しいキーで更新
  3. 動作を確認
  4. 古いキーを削除

最小権限の原則

必要最小限のスコープのみを付与してください：

// ❌ 悪い例: すべてのスコープを付与
{
  "name": "My Key",
  "scopes": ["read:jobs", "write:jobs", "read:logs", "write:logs", "read:keys", "write:keys"]
}

// ✅ 良い例: 必要なスコープのみ
{
  "name": "Read-only Key",
  "scopes": ["read:jobs", "read:logs"]
}

キーの命名

APIキーには用途を示す明確な名前を付けてください：

  • ✅ Production Server API Key
  • ✅ CI/CD Pipeline Key
  • ✅ Monitoring Service Key
  • ❌ Key 1
  • ❌ Test

制限と使用量追跡

APIキー作成制限

APIキーを作成する際、以下の制限がチェックされます：

  1. 現在のAPIキー数: 最大10個まで
  2. 今日の活動: 今日の作成・削除活動が上限（20回）を超えていないか
制限チェック = (現在のAPIキー数 < 10) AND (今日の活動 < 20)

例:

  • 現在5キー、今日2回作成・1回削除 → 作成可能
  • 現在10キー → 作成不可（上限到達）
  • 今日10回作成・10回削除 → 作成不可（活動上限到達）

API呼び出し制限

APIキーを使用してAPIを呼び出す際、以下の制限がチェックされます：

  1. 日次呼び出し回数: プランごとの1日あたりの上限
    • Free: 100回/日
    • Hobby: 500回/日
    • Pro: 2,000回/日

API呼び出しが上限に達すると、以下のエラーが返されます：

{
  "success": false,
  "message": "本日のAPI呼び出し上限 (100 回) に達しています。現在: 100 回",
  "data": null
}

APIキー削除時の記録

APIキーを削除しても使用履歴はリセットされません：

  • 削除されたAPIキーのIDと削除日時が ResourceHistory に記録されます
  • 削除されたAPIキーの呼び出し回数は日次・月次使用量に累積されたまま残ります
  • 今日の削除回数もカウントされ、作成制限に影響します

使用量の確認

GET /api/usage エンドポイントで現在の使用状況を確認できます。

curl -X GET https://your-domain.com/api/usage \
  -H "Authorization: Bearer YOUR_API_TOKEN"

詳細は Usage API (usage-api.md) をご覧ください。

よくあるエラー

APIキー数の上限

エラー:

{
  "success": false,
  "message": "APIキーの上限 (10 件) に達しています。",
  "data": null
}

解決方法:

  1. 不要なAPIキーを削除する
  2. 既存のキーを複数の用途で共有する（スコープに注意）

API呼び出し上限

エラー:

{
  "success": false,
  "message": "本日のAPI呼び出し上限 (100 回) に達しています。現在: 100 回",
  "data": null
}

解決方法:

  1. 翌日0時（タイムゾーン基準）まで待つ
  2. 不要なAPI呼び出しを削減する
  3. より高い上限が必要な場合はプランをアップグレードする

活動上限に達した

エラー:

{
  "success": false,
  "message": "本日のAPIキー作成・削除活動が上限に達しています。明日再度お試しください。",
  "data": null
}

解決方法:

  1. 翌日まで待つ
  2. APIキーの作成・削除を計画的に行う
  3. 異常に多い削除・作成を行っている場合は、ワークフローを見直す
← Previous
Jobs API
Next →
Webhooks API
← Back to Documentation