Bearer Authentication

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:

1
Authorization: Bearer <token>

The Bearer authentication scheme was originally created as part of OAuth 2.0 in RFC 6750, but is sometimes also used on its own. 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:

1
openapi: 3.0.0
2
---
3
# 1) Define the security scheme type (HTTP bearer)
4
components:
5
  securitySchemes:
6
    bearerAuth: # arbitrary name for the security scheme
7
      type: http
8
      scheme: bearer
9
      bearerFormat: JWT # optional, arbitrary value for documentation purposes
10

11
# 2) Apply the security globally to all operations
12
security:
13
  - bearerAuth: [] # use the same name as above

Optional 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:

1
paths:
2
  /something:
3
    get:
4
      security:
5
        - bearerAuth: []

Bearer authentication can also be combined with other authentication methods as explained in Using Multiple Authentication Types.

401 Response

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 $ref.

1
paths:
2
  /something:
3
    get:
4
      ...
5
      responses:
6
        '401':
7
          $ref: '#/components/responses/UnauthorizedError'
8
        ...
9
    post:
10
      ...
11
      responses:
12
        '401':
13
          $ref: '#/components/responses/UnauthorizedError'
14
        ...
15

16
components:
17
  responses:
18
    UnauthorizedError:
19
      description: Access token is missing or invalid

To learn more about responses, see Describing Responses.

Did not find what you were looking for? Ask the community
Found a mistake? Let us know