OAS 3 This page applies to OpenAPI 3 – the latest version of the OpenAPI Specification.
If you use OpenAPI 2 (fka Swagger), visit OpenAPI 2 pages.
Authentication and Authorization
OpenAPI uses the term security scheme for authentication and authorization schemes. OpenAPI 3.0 lets you describe APIs protected using the following security schemes:
- HTTP authentication schemes (they use the
- API keys in headers, query string or cookies
- OAuth 2
- OpenID Connect Discovery
Follow the links above for the guides on specific security types, or continue reading to learn how to describe security in general.
Changes from OpenAPI 2.0
If you used OpenAPI 2.0 before, here is a summary of changes to help you get started with OpenAPI 3.0:
securityDefinitionswere renamed to
securitySchemesand moved inside
type: basicwas replaced with
- The new
type: httpis an umbrella type for all HTTP security schemes, including Basic, Bearer and other, and the
schemekeyword indicates the scheme type.
- API keys can now be sent
- Added support for OpenID Connect Discovery (
- OAuth 2 security schemes can now define multiple
- OAuth 2 flows were renamed to match the OAuth 2 Specification:
Security is described using the
security keywords. You use
securitySchemes to define all security schemes your API supports, then use
security to apply specific schemes to the whole API or individual operations.
Step 1. Defining securitySchemes
All security schemes used by the API must be defined in the global
components/securitySchemes section. This section contains a list of named security schemes, where each scheme can be of
http– for Basic, Bearer and other HTTP authentications schemes
apiKey– for API keys and cookie authentication
oauth2– for OAuth 2
openIdConnect– for OpenID Connect Discovery
Other required properties for security schemes depend on the
The following example shows how various security schemes are defined. The BasicAuth, BearerAuth names and others are arbitrary names that will be used to refer to these definitions from other places in the spec.
components: securitySchemes: BasicAuth: type: http scheme: basic BearerAuth: type: http scheme: bearer ApiKeyAuth: type: apiKey in: header name: X-API-Key OpenID: type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://example.com/oauth/authorize tokenUrl: https://example.com/oauth/token scopes: read: Grants read access write: Grants write access admin: Grants access to admin operations
Step 2. Applying security
After you have defined the security schemes in the
securitySchemes section, you can apply them to the whole API or individual operations by adding the
security section on the root level or operation level, respectively.
When used on the root level,
security applies the specified security schemes globally to all API operations, unless overridden on the operation level. In the following example, the API calls can be authenticated using either an API key or OAuth 2. The ApiKeyAuth and OAuth2 names refer to the schemes previously defined in
security: - ApiKeyAuth:  - OAuth2: - read - write # The syntax is: # - scheme name: # - scope 1 # - scope 2
For each scheme, you specify a list of security scopes required for API calls (see below). Scopes are used only for OAuth 2 and OpenID Connect Discovery; other security schemes use an empty array
security can be overridden in individual operations to use a different authentication type, different OAuth/OpenID scopes, or no authentication at all:
paths: /billing_info: get: summary: Gets the account billing info security: - OAuth2: [admin] # Use OAuth with a different scope responses: '200': description: OK '401': description: Not authenticated '403': description: Access token does not have the required scope /ping: get: summary: Checks if the server is running security:  # No security responses: '200': description: Server is up and running default: description: Something is wrong
OAuth 2 and OpenID Connect use scopes to control permissions to various user resources. For example, the scopes for a pet store may include
security, the entries corresponding to OAuth 2 and OpenID Connect need to specify a list of scopes required for a specific operation (if
security is used on the operation level) or all API calls (if
security is used on the root level).
security: - OAuth2: - scope1 - scope2 - OpenId: - scopeA - scopeB - BasicAuth: 
- In case of OAuth 2, the scopes used in
securitymust be previously defined in
- In case of OpenID Connect Discovery, possible scopes are listed in the discovery endpoint specified by
- Other schemes (Basic, Bearer, API keys and others) do not use scopes, so their
securityentries specify an empty array
Different operations typically require different scopes, such as read vs write vs admin. In this case, you should apply scoped
security to specific operations instead of doing it globally.
# Instead of this: # security: # - OAuth2: # - read # - write # Do this: paths: /users: get: summary: Get a list of users security: - OAuth2: [read] # <------ ... post: summary: Add a user security: - OAuth2: [write] # <------ ...
Using Multiple Authentication Types
Some REST APIs support several authentication types. The
security section lets you combine the security requirements using logical OR and AND to achieve the desired result.
security uses the following logic:
security: # A OR B - A - B
security: # A AND B - A B
security: # (A AND B) OR (C AND D) - A B - C D
security is an array of hashmaps, where each hashmap contains one or more named security schemes. Items in a hashmap are combined using logical AND, and array items are combined using logical OR. Security schemes combined via OR are alternatives – any one can be used in the given context. Security schemes combined via AND must be used simultaneously in the same request.
Here, we can use either Basic authentication or an API key:
security: - basicAuth:  - apiKey: 
Here, the API requires a pair of API keys to be included in requests:
security: - apiKey1:  apiKey2: 
Here, we can use either OAuth 2 or a pair of API keys:
security: - oauth2: [scope1, scope2] - apiKey1:  apiKey2: