The HTTP security scheme in OpenAPI

The http security scheme is one of the most commonly used schemes because it covers anything using the HTTP header Authorization. This is a long list, including auth schemes like HTTP Basic, HTTP Digest, and HTTP Bearer. The full list of supported auth schemes for type: http is outsourced to the IANA HTTP Authentication Scheme Registry .

Of that list, the auth schemes most likely to be used for a modern API are:

• Bearer
• Basic
• Digest

HTTP Bearer

The Bearer auth scheme allows you to pass a token, which could be a JSON Web Token (JWT), API token, access token, or other token-based form of authentication.

Bearer is generally used for short-lived tokens granted to your API users through an additional login mechanism. Using a JWT allows for storing additional metadata within the token, which can be helpful for some use cases, such as storing scopes for permissions models.

The fields for a Bearer auth scheme are as follows:

So, for example, a JWT might look like this:

HTTP Basic

The Basic auth scheme is a simple authentication mechanism baked into the HTTP protocol that supports sending an Authorization header containing a Base64-encoded username and password.

Basic is a relatively simple mechanism for getting started, but it risks leaking easy-to-decode passwords if used incorrectly. The example above is simply a base64("user:password") but it can fool some developers into thinking the password is actually encrypted or secret.

Much like API keys, another issue with Basic is that it generally works with long-lived credentials, and if intercepted, these can be used by malicious actors until the credentials expire or are revoked.

For these reasons it is generally best to avoid HTTP Basic.

Since all APIs need to be accurately described (warts and all), here’s how to describe a Basic auth scheme in OpenAPI:

For example:

The description field can be used to warn developers about the risks of using Basic authentication, and to encourage them to use more secure alternatives like Bearer tokens or OAuth 2.0.

HTTP Digest

The Digest auth scheme is a more secure alternative to Basic authentication. Instead of sending the username and password in plain text, Digest uses a challenge-response mechanism that hashes credentials with a nonce provided by the server. This helps protect against replay attacks and credential interception.

A typical Digest authentication request looks like this:

The fields for a Digest auth scheme in OpenAPI are as follows:

For example:

Overlap with other security schemes

The HTTP security scheme overlaps with a few other, more specific schemes.

The API Key security scheme is better suited to non-standard API keys using custom headers, like Acme-API-Key, whereas the HTTP security scheme is specifically designed for HTTP-based authentication methods using the Authorization header.

The HTTP security scheme also has some overlap with the OAuth 2.0 and OpenID Connect security schemes. These may use bearer tokens and the JWT format, but they are more complex and involve additional flows and endpoints. It’s better to use the oauth2 or openidConnect security scheme for an API using the OAuth 2.0 or OpenID Connect protocol than to try to cover it with the http security scheme.

Unauthorized response

As well as describing the security requirements, it also helps to describe what happens when those requirements are not met.

The 401 Unauthorized response can be returned for requests with missing security credentials, showing what the client can expect to see if this happens. This response includes the WWW-Authenticate header, which you may want to mention. As with other generic responses, the 401 response can be defined as a component in the responses section, and referenced with $ref to avoid repetition.

Learn more about describing responses.

Forbidden response

The 403 Forbidden response can be returned for requests that are authenticated but not authorized to access the resource. This response can also include the WWW-Authenticate header, but it is not required.

As with the 401 response, the 403 response can be defined as a component in the responses section, and referenced with $ref to avoid repetition. This error uses the HTTP Problem Details format, which is a standard means of providing more information about the error.