API キー

一部のAPIでは、認証にAPIキーを使用します。APIキーは、クライアントがAPI呼び出しを行う際に提供する必要がある特別なトークンです。キーは通常、リクエストヘッダーとして送信されます。

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

またはクエリパラメータとして

1
GET /something?api_key=abcdef12345

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

APIキーベースのセキュリティを定義するには

グローバルなsecurityDefinitionsセクションにtype: apiKeyのエントリを追加します。エントリ名は任意（下記の例では*APIKeyHeader*）であり、仕様の他の部分からこのセキュリティ定義を参照するために使用されます。
APIキーがin: headerで渡されるか、in: queryで渡されるかを指定します。
そのパラメーターまたはヘッダーのnameを指定します。

1
securityDefinitions:
2
  # X-API-Key: abcdef12345
3
  APIKeyHeader:
4
    type: apiKey
5
    in: header
6
    name: X-API-Key
7
  # /path?api_key=abcdef12345
8
  APIKeyQueryParam:
9
    type: apiKey
10
    in: query
11
    name: api_key

次に、ルートレベルまたは操作レベルのsecurityセクションを使用して、APIキーをAPI全体または特定の操作に適用します。

1
# Global security (applies to all operations):
2
security:
3
  - APIKeyHeader: []
4
paths:
5
  /something:
6
    get:
7
      # Operation-specific security:
8
      security:
9
        - APIKeyQueryParam: []
10
      responses:
11
        200:
12
          description: OK (successfully authenticated)

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

APIキーのペア

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

1
securityDefinitions:
2
  apiKey:
3
    type: apiKey
4
    in: header
5
    name: X-API-KEY
6
  appId:
7
    type: apiKey
8
    in: header
9
    name: X-APP-ID
10
security:
11
  - apiKey: []
12
    appId: []

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

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

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

401レスポンス

また、APIキーが不足しているか無効なリクエストに対して返される401「Unauthorized」レスポンスを定義することもできます。このレスポンスには、言及したいWWW-Authenticateヘッダーが含まれます。他の一般的なレスポンスと同様に、401レスポンスはグローバルなresponsesセクションで定義し、複数の操作から参照できます。

1
paths:
2
  /something:
3
    get:
4
      ...
5
      responses:
6
        ...
7
        401:
8
            $ref: '#/responses/UnauthorizedError'
9
    post:
10
      ...
11
      responses:
12
        ...
13
        401:
14
          $ref: '#/responses/UnauthorizedError'
15
responses:
16
  UnauthorizedError:
17
    description: API key is missing or invalid
18
    headers:
19
      WWW_Authenticate:
20
        type: string

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