OAS 3 This page applies to OpenAPI 3 – the latest version of the OpenAPI Specification.
Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.”
The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the
Authorization header when making requests to protected resources:
Authorization: Bearer <token>
Similarly to Basic authentication, Bearer authentication should only be used over HTTPS (SSL).
Describing Bearer Authentication
In OpenAPI 3.0, Bearer authentication is a security scheme with
type: http and
scheme: bearer. You first need to define the security scheme under
components/securitySchemes, then use the
security keyword to apply this scheme to the desired scope – global (as in the example below) or specific operations:
openapi: 3.0.0 ... # 1) Define the security scheme type (HTTP bearer) components: securitySchemes: bearerAuth: # arbitrary name for the security scheme type: http scheme: bearer bearerFormat: JWT # optional, arbitrary value for documentation purposes # 2) Apply the security globally to all operations security: - bearerAuth:  # use the same name as above
bearerFormat is an arbitrary string that specifies how the bearer token is formatted. Since bearer tokens are usually generated by the server,
bearerFormat is used mainly for documentation purposes, as a hint to the clients. In the example above, it is “JWT”, meaning JSON Web Token.
The square brackets
 in bearerAuth:  contain a list of security scopes required for API calls. The list is empty because scopes are only used with OAuth 2 and OpenID Connect.
In the example above, Bearer authentication is applied globally to the whole API. If you need to apply it to just a few operations, add
security on the operation level instead of doing this globally:
paths: /something: get: security: - bearerAuth: 
Bearer authentication can also be combined with other authentication methods as explained in Using Multiple Authentication Types.
You can also define the 401 “Unauthorized” response returned for requests that do not contain a proper bearer token. Since the 401 response will be used by multiple operations, you can define it in the global
components/responses section and reference elsewhere via
paths: /something: get: ... responses: '401': $ref: '#/components/responses/UnauthorizedError' ... post: ... responses: '401': $ref: '#/components/responses/UnauthorizedError' ... components: responses: UnauthorizedError: description: Access token is missing or invalid
To learn more about
responses, see Describing Responses.