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.

Basic Authentication

Basic authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password. For example, to authorize as demo / p@55w0rd the client would send

Authorization: Basic ZGVtbzpwQDU1dzByZA==

Note: Because base64 is easily decoded, Basic authentication should only be used together with other security mechanisms such as HTTPS/SSL.

Describing Basic Authentication

Using OpenAPI 3.0, you can describe Basic authentication as follows:

openapi: 3.0.0
...

components:
  securitySchemes:
    basicAuth:     # <-- arbitrary name for the security scheme
      type: http
      scheme: basic

security:
  - basicAuth: []  # <-- use the same name here

The first section, securitySchemes, defines a security scheme named basicAuth (an arbitrary name). This scheme must have type: http and scheme: basic. The security section then applies Basic authentication to the entire API. The square brackets [] denote the security scopes used; the list is empty because Basic authentication does not use scopes. security can be set globally (as in the example above) or on the operation level. The latter is useful if only a subset of operations require Basic authentication:

paths:
  /something:
    get:
      security:
        - basicAuth:[]

Basic 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 with missing or incorrect credentials. This response includes the WWW-Authenticate header, which you may want to mention. As with other common responses, the 401 response can be defined in the global components/responses section and referenced elsewhere via $ref.

paths:
  /something:
    get:
      ...
      responses:
        ...
        '401':
           $ref: '#/components/responses/UnauthorizedError'
    post:
      ...
      responses:
        ...
        '401':
          $ref: '#/components/responses/UnauthorizedError'
...
components:
  responses:
    UnauthorizedError:
      description: Authentication information is missing or invalid
      headers:
        WWW_Authenticate:
          schema:
            type: string

To learn more about the responses syntax, see Describing Responses.

  

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