API キー

一部のAPIは認証にAPIキーを使用します。APIキーは、クライアントがAPI呼び出しを行う際に提供するトークンです。キーはクエリ文字列で送信できます

1
GET /something?api_key=abcdef12345

またはリクエストヘッダーとして

1
GET /something HTTP/1.1
2
X-API-Key: abcdef12345

またはクッキーとして

1
GET /something HTTP/1.1
2
Cookie: X-API-KEY=abcdef12345

APIキーは、クライアントとサーバーのみが知る秘密であるとされています。Basic認証と同様に、APIキーベースの認証は、HTTPS/SSLなどの他のセキュリティメカニズムと併用する場合にのみ安全と見なされます。

APIキーの記述

OpenAPI 3.0では、APIキーは次のように記述されます。

1
openapi: 3.0.4
2
---
3
# 1) Define the key name and location
4
components:
5
  securitySchemes:
6
    ApiKeyAuth: # arbitrary name for the security scheme
7
      type: apiKey
8
      in: header # can be "header", "query" or "cookie"
9
      name: X-API-KEY # name of the header, query parameter or cookie
10

11
# 2) Apply the API key globally to all operations
12
security:
13
  - ApiKeyAuth: [] # use the same name as under securitySchemes

この例では、リクエストヘッダー X-API-Key: <key> として送信される X-API-Key という名前のAPIキーを定義しています。キー名 ApiKeyAuth はセキュリティスキームの任意の名前であり（name キーで指定されるAPIキー名と混同しないでください）、このセキュリティスキームをAPIに適用するために security セクションで再び使用されます。注意： securitySchemes セクションだけでは不十分です。security も使用してAPIキーを有効にする必要があります。security はグローバルにではなく、操作レベルで設定することもできます。これは、一部の操作のみにAPIキーが必要な場合に便利です。

1
paths:
2
  /something:
3
    get:
4
      # Operation-specific security:
5
      security:
6
        - ApiKeyAuth: []
7
      responses:
8
        "200":
9
          description: OK (successfully authenticated)

1つのAPIで複数の認証タイプをサポートできることに注意してください。複数の認証タイプの使用を参照してください。

複数のAPIキー

一部のAPIは、APIキーとApp IDのように、セキュリティキーのペアを使用します。キーが一緒に使用されること（論理AND）を指定するには、security 配列の同じ配列項目にそれらをリストします。

1
components:
2
  securitySchemes:
3
    apiKey:
4
      type: apiKey
5
      in: header
6
      name: X-API-KEY
7
    appId:
8
      type: apiKey
9
      in: header
10
      name: X-APP-ID
11

12
security:
13
  - apiKey: []
14
    appId: [] # <-- no leading dash (-)

以下の違いに注意してください。

1
security:
2
  - apiKey: []
3
  - appId: []

これは、どちらかのキーを使用できることを意味します（論理OR）。より多くの例については、複数の認証タイプの使用を参照してください。

401レスポンス

APIキーがない、または無効なリクエストに対して返される401「Unauthorized」レスポンスを定義できます。このレスポンスには WWW-Authenticate ヘッダーが含まれており、言及したい場合があるでしょう。他の一般的なレスポンスと同様に、401レスポンスはグローバルな components/responses セクションで定義し、$ref を介して他の場所から参照できます。

1
paths:
2
  /something:
3
    get:
4
      ...
5
      responses:
6
        ...
7
        '401':
8
            $ref: "#/components/responses/UnauthorizedError"
9
    post:
10
      ...
11
      responses:
12
        ...
13
        '401':
14
          $ref: "#/components/responses/UnauthorizedError"
15

16
components:
17
  responses:
18
    UnauthorizedError:
19
      description: API key is missing or invalid
20
      headers:
21
        WWW_Authenticate:
22
          schema:
23
            type: string

レスポンスの記述について詳しくは、レスポンスの記述を参照してください。

お探しのものが見つかりませんでしたか？コミュニティに質問する
間違いを見つけましたか？お知らせください