コンテンツにスキップ

MCP API キー作成

メソッド

RESTメソッドを採用しています。

HTTPメソッド

POST: MCP APIキー作成

命名規則

クエリパラメータとノードの命名を統一し、可読性を向上させるため、リクエスト時のURIとJSON内のノードにはsnake_caseを使用します。

リクエストとレスポンス

ヘッダー

メタ情報はレスポンスボディではなく、HTTPヘッダーに設定されます。

リクエストヘッダー

  • Authorization
  • Content-Type
  • Accept
  • Accept-language

レスポンスヘッダー

  • Content-Type

MCP APIキー作成

URI

POST /v1/organizations/{organization_id}/projects/{project_id}/mcp_api_key

パスパラメータ

名前 型 必須 説明
organization_id integer 必須 組織ID
project_id integer 必須 プロジェクトID

リクエストボディ

リクエストボディはJSONです。

{
  "scope": "project",
  "name": "mcp for project A",
  "keyPrefix": "abc123",
  "permission": 0,
  "expiresAt": 1735689600000
}

リクエストパラメータ

名前 型 必須 説明
scope string 必須 APIキーのスコープ（user または project）
name string 必須 APIキーの名前（最大255文字）
keyPrefix string 必須 キープレフィックス（最大100文字、ユニーク）
permission integer 任意 アクセス権限（0: READ、1: WRITE、デフォルト: 0）
expiresAt integer 任意 有効期限（エポックミリ秒、未指定時は作成日+30日）

レスポンス

レスポンスはJSONです（HTTPステータス: 201 Created）。

{
  "id": 1,
  "userId": 1,
  "projectId": 2,
  "name": "mcp for project A",
  "keyPrefix": "abc123",
  "apiKey": "guinness_abc123_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "permission": 0,
  "expiresAt": 1735689600000,
  "revokedAt": null,
  "lastUsedAt": null,
  "createdAt": 1234567890000,
  "updatedAt": 1234567890000,
  "deletedAt": null,
  "createdBy": "user-cognito-sub",
  "updatedBy": "user-cognito-sub",
  "deletedBy": null
}

重要: apiKeyは作成時に一度だけ返されます。以降のリクエストでは返されません。

認証

認証はAmazon Cognitoから発行されるJSON Web Tokens (JWT)を使用して行われます。

例外処理

例外処理のステータスコードは以下の通りです。

説明 ステータスコード ステータス名
無効なリクエスト（スコープが無効、名前が空など） 400 Bad Request
認証情報不足 401 Unauthorized
実行権限不足 403 Forbidden
組織またはプロジェクトが見つかりません 404 Not Found
keyPrefixが既に使用されています 409 Conflict
内部サーバーエラー 500 Internal Server Error

処理フロー

  1. パスパラメータから組織IDとプロジェクトIDを抽出
  2. リクエストボディから各フィールドを抽出
  3. スコープに応じて、userIdまたはprojectIdを設定
  4. keyPrefixがユニークであることを検証
  5. ユーザーまたはプロジェクトへのアクセス権限を確認
  6. expiresAtが未指定の場合、作成日+30日を設定
  7. ランダムなsalt値とsecretsを生成
  8. APIキーを生成（形式: guinness_{keyPrefix}_{secrets}）
  9. キーをハッシュ化してデータベースに保存
  10. 作成されたAPIキー情報を返す（実際のキーはこの時のみ）

APIキー構造

APIキーは以下の形式で生成されます： 

guinness_{key_prefix}_{secrets}

例: guinness_abc123_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

セキュリティ

  • APIキーはハッシュ化されて保存されます（key_hashとsalt）
  • 実際のAPIキーは作成レスポンスでのみ返されます
  • keyPrefixはユニークである必要があります

詳細フローチャート

flowchart TD
    Start([POST Request]) --> Auth[認証・パラメータ取得]
    Auth --> Service[Service Layer]
    Service --> AccessCheck[権限チェック]
    AccessCheck --> HasAccess{Write権限?}
    HasAccess -->|なし| Err404[404 Not Found]
    HasAccess -->|あり| Validate[入力検証]
    Validate --> ValidScope{scope検証}
    ValidScope -->|NG| Err400[400 Bad Request]
    ValidScope -->|OK| CheckPrefix[keyPrefix重複確認]
    CheckPrefix --> Duplicate{重複?}
    Duplicate -->|Yes| Err409[409 Conflict]
    Duplicate -->|No| CreateDB[DB作成<br/>APIキー生成]
    CreateDB --> Success[201 Created]