Security schemes in OpenAPI

Most APIs have some form of authorization and/or authentication, from simple API keys to scope-based OAuth 2 tokens on a tight rotation. APIs might support multiple methods in various combinations, so describing what goes where can become a bit of a challenge. OpenAPI helps by supporting a wide array of authorization and authentication methods, all of which can described under the larger umbrella of Security Schemes.

Security scheme objects are defined in the Components Object in the securitySchemes section, and the security field references them. The security field is an array of security requirement objects, which are maps of security scheme names to scopes.

Each security scheme has a unique name in the securitySchemes map, and the type field specifies which authentication or authorization method will be used from a predefined list of supported types.

Security types

The following authorization/authentication types are supported by OpenAPI as of v3.1:

• API Key
• HTTP Authorization (E.g: Basic, Digest, Bearer, and more)
• OAuth 2.0
• OpenID Connect
• Mutual TLS

OpenAPI example security scheme schema

Here’s an example security schemes object with the sort of values likely to be used. The names are arbitrary and just used for clarity, but could be whatever you want.

To learn more about different types of security schemes, take a look at the guides for API Key, HTTP Authorization (Basic, Digest, Bearer, and more), OAuth 2.0, OpenID Connect, or Mutual TLS.

Security requirements

Once these security schemes are defined, they can be referenced by the security keyword.

Learn more about security requirements in the Security Requirements section.