Security

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

Describing Bearer Authentication

      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: [] 

      * 3) Apply the security on API
      paths:
        /something:
          get:
            security:
              - 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.

    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