OpenAPIでのAPIキー認証

OpenAPIでのAPIキー認証

APIキー認証は、クライアントが各リクエストに秘密鍵を含めるシンプルで広く使用されている方法です。OpenAPIはヘッダー、クエリパラメータ、またはCookieで送信されるAPIキーのドキュメント化をサポートしています。

ヘッダーベースのAPIキー

最も一般的なパターン — カスタムヘッダー：

components:
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 登録時に提供されるAPIキー

クライアントの使用法：X-API-Key: sk_live_abc123...

クエリパラメータAPIキー

セキュリティは低いがシンプルさのために使用される場合があります：

components:
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key

クライアントの使用法：GET /data?api_key=sk_live_abc123

APIキーセキュリティの適用

グローバルまたはエンドポイントごとに適用：

# グローバル — すべてのエンドポイントでAPIキーが必要
security:
  - apiKeyHeader: []

paths:
  /public/health:
    get:
      security: []   # オーバーライド：認証不要
      summary: ヘルスチェック

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

• 常にHTTPSを使用（servers に https:// を記載）
• クエリパラメータよりヘッダーベースのキーを優先（URLはログに記録される）
• APIキーローテーションのガイダンスを説明に含める
• テスト/本番など異なるキータイプがある場合はドキュメント化する