Security schemes in OpenAPI

Most APIs have some form of authorization and 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 you can describe 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. The type field specifies which authentication or authorization method (from a predefined list of supported types) is used.

Security types

The following authorization and authentication types are supported by the OpenAPI Specification 3.1:

• API Key
• HTTP Authorization (such as Basic, Digest, and Bearer)
• OAuth 2.0
• OpenID Connect
• Mutual TLS

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. You can use any names you want.

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

Security requirements

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

Learn more about security in the security requirements documentation.