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 big list, including auth schemes like HTTP Basic, HTTP Digest, and Bearer. The full list of supports auth schemes for type: http is outsourced to the IANA HTTP Authentication Scheme Registry .

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

• Bearer
• Basic
• Digest

HTTP Bearer

The Bearer security scheme allows passing a token, which could be a JWT, API token, access token, or anything else.

The Bearer security scheme 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 security scheme are as follows:

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

HTTP Basic

The Basic security 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 relatively simple mechanism to get started with, but risks leaking easy-to-decode passwords if used incorrectly. The example above is simply base64("user:password"), but can fool some developers into thinking its actually encrypted or secret.

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

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 HTTP Basic 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 OAuth2.

HTTP Digest

The Digest security scheme is a more secure alternative to Basic authentication. Instead of sending the username and password in plain text, Digest authentication 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 security 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 for non-standard API keys using custom headers like Acme-API-Key, whereas HTTP security schemes are specifically designed for HTTP-based authentication methods using Authorization header.

There is also some overlap with OAuth2 and OpenID Connect security schemes. These may use bearer tokens, and they may use the JWT format, but they are more complex and involve additional flows and endpoints. The oauth2 and openidConnect security schemes are better suited for any APIs using the OAuth 2.0 and OpenID Connect protocols than trying to cover it with the http security scheme.

Unauthorized Response

As well as describing the security requirements, it also helps to describe what will happen 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 is using the HTTP Problem Details format, which is a standard way to provide more information about the error.