OAS 2 This page applies to OpenAPI Specification ver. 2 (fka Swagger). To learn about the latest version, visit OpenAPI 3 pages.
Some APIs use API keys for authorization. An API key is a special token that the client needs to provide when making API calls. The key is usually sent as a request header:
GET /something HTTP/1.1
or as a query parameter:
API keys are supposed to be a secret that only the client and server know. But, as well as Basic authentication, API key-based authentication is not considered secure unless used together with other security mechanisms such as HTTPS/SSL.
To define API key-based security:
- Add an entry with
type: apiKey in the global
securityDefinitions section. The entry name can be arbitrary (such as APIKeyHeader in the example below) and is used to refer to this security definition from other parts of the spec.
- Specify whether the API key will be passed
in: header or
- Specify a
name for that parameter or header.
# X-API-Key: abcdef12345
Then, use the
section on the root level or operation level to apply API keys to the whole API or specific operations.
# Global security (applies to all operations):
- APIKeyHeader: 
# Operation-specific security:
- APIKeyQueryParam: 
description: OK (successfully authenticated)
Note that it is possible to support multiple authorization types in an API. See Using Multiple Authentication Types
Pair of API Keys
Some APIs use a pair of security keys, say, API Key and App ID. To specify that the keys are used together (as in logical AND), list them in the same array item in the
- apiKey: 
Note the difference from:
- apiKey: 
- appId: 
which means either key can be used (as in logical OR). For more examples, see Using Multiple Authentication Types
You can also define the 401 "Unauthorized" response returned for requests with missing or invalid API key. This response includes the
header, which you may want to mention. As with other common responses, the 401 response can be defined in the global
section and referenced from multiple operations.
description: API key is missing or invalid
Did not find what you were looking for? Ask the community
Found a mistake? Let us know