OAS 2 このページはOpenAPI仕様バージョン2（旧称Swagger）に適用されます。最新バージョンについては、OpenAPI 3のページをご覧ください。

APIキー

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

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

またはクエリパラメータとして送信されます

GET /something?api_key=abcdef12345

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

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

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

securityDefinitions:
   # X-API-Key: abcdef12345
   APIKeyHeader:
     type: apiKey
     in: header
     name: X-API-Key
   # /path?api_key=abcdef12345
   APIKeyQueryParam:
     type: apiKey
     in: query
     name: api_key

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

# Global security (applies to all operations):
security:
  - APIKeyHeader: []
paths:
  /something:
    get:
      # Operation-specific security:
      security:
        - APIKeyQueryParam: []
      responses:
        200:
          description: OK (successfully authenticated)

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

APIキーのペア

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

securityDefinitions:
  apiKey:
    type: apiKey
    in: header
    name: X-API-KEY
  appId:
    type: apiKey
    in: header
    name: X-APP-ID
security:
  - apiKey: []
    appId: []

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

security:
  - apiKey: []
  - appId: []

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

401レスポンス

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

paths:
  /something:
    get:
      ...
      responses:
        ...
        401:
           $ref: '#/responses/UnauthorizedError'
    post:
      ...
      responses:
        ...
        401:
          $ref: '#/responses/UnauthorizedError'
responses:
  UnauthorizedError:
    description: API key is missing or invalid
    headers:
      WWW_Authenticate:
        type: string

  

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