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 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 is 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.
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
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.