OpenAPI: APIキーヘッダー認証

OpenAPIでのAPIキー認証の文書化

APIキー認証はJWTやOAuth2よりシンプルで、サーバー間通信、レート制限付きパブリックAPI、開発者ポータルによく使用されます。

セキュリティスキーム定義

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key provided by the developer portal

OpenAPIはAPIキーの3つの場所をサポートしています：header、query、cookie。ヘッダーベースが最もセキュアで、URLやサーバーログにキーが表示されません。

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

security:
  - ApiKeyAuth: []

paths:
  /data/export:
    get:
      summary: Export data
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Data exported successfully
        '401':
          description: Missing or invalid API key
        '403':
          description: API key does not have permission
        '429':
          description: Rate limit exceeded

APIキー認証のエラーレスポンス

クライアントが遭遇する具体的なエラーレスポンスを文書化します：

ステータス	タイミング
401	APIキーヘッダーが欠落しているか、キーが無効/期限切れ
403	キーは有効だが、要求されたリソースへの権限がない
429	キーがレート制限の割当を超過した

キーローテーションの考慮事項

API説明に、キーを再生成できるか、古いキーに猶予期間があるか、クライアントがキーの期限切れをどう処理すべきかを文書化します。この情報はOpenAPI仕様の正式な一部ではありませんが、利用者が正しく統合するのに役立ちます。

複数の認証オプション

セキュリティ配列にAPIキーとBearerトークン認証を代替として列挙できます。これにより内部サービスはAPIキーを使用し、ユーザー向けクライアントはJWTトークンを使用できます。