OpenAPI Security

When designing an API, it is important to consider the security requirements for accessing the API. OpenAPI 3.1 provides a way to define security requirements at both the document and operation levels.

Firstly, “security” is a general term which covers multiple authentication and authorization systems which are commonly used to keep API operations being used by only the intended actors.

In OpenAPI this is broken in two halves.

1. Security schemes
2. Security requirements

Security schemes are defined as reusable components. Security requirements invoke those schemes across the whole API, or on specific operations.

Here’s the basic structure of how security is defined in OpenAPI using a simple API key example:

Supported security schemes in OpenAPI

Before referencing a security scheme as a requirement in the security section, it must be defined in the Components Object under securitySchemes.

OpenAPI v3.1 supports the following security schemes:

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

Once there are security schemes defined, they can be referenced in the security section of the OpenAPI document or at the operation level.

Security Requirement Object

A Security Requirement Object defines a map of security scheme names, with an array of scopes or roles that are required to access an API (or specific operation).

The names must match the names of Security Scheme Objects defined in the Components Object under the securitySchemes field.

Global authentication vs endpoint authentication

Security can be applied at two levels in OpenAPI:

• Global security: the security specified is available for all operations.
• Per operation security: only applied to the operation, overriding any global level security.

Here is an example of describing security in the ways mentioned above:

The important parts of the above example are the security  and securitySchemes  sections.

Working with security requirements

Depending on the API, security requirements can be simple or complex. Some examples should hopefully help to illustrate how to work with security requirements in OpenAPI.

Simple API Security

All operations in an API may require an API key for access. This can be defined at the document level using the security section.

Public Reads, Protected Writes

A simple API might have some publicly accessible endpoints, but require an API key for others. The security section can be used to define the security requirements for the entire API or for specific operations.

Multiple Security Schemes

A more complex API might require different security requirements for different operations, or even allow multiple security schemes to be used interchangeably.

Here is an example where the API can be accessed with either an API key or OAuth 2.0. OAuth 2 allows for more granular access control using the concept of scopes, which can be defined in the securitySchemes section and referred to in the security section for specific operations.

Security requirement scopes or roles in openapi

When defining an OAuth 2.0 or OpenID Connect Security Requirement Object for an operation, the {securitySchemeName} field should contain a list of scopes or roles required for the security scheme.

For example, the following security requirement object requires the read and write scopes for the oauth2 security scheme:

Disabling security requirements

Security can be disabled for a specific operation by providing an empty array ([]) in the list of security requirements.

In this example, the POST operation in the /auth path does not require security, despite the global security requirement of an API key:

Optional security

Security can also be made optional by providing an empty object ({}) in the list of security requirements.

In this example, the API may be accessed with or without an API key:

Adding optional security to a specific operation

Security can be made optional for a specific operation by providing an empty object ({}) in the list of security requirements.

This does not disable the security requirements defined at the document level, but makes them optional for this specific operation.

In this example, the GET operation in the /drinks path may be accessed with or without an API key, but if authenticated, the response will include additional information:

Requiring multiple security schemes together

If multiple schemes are required together, then the Security Requirement Object should be defined with multiple security schemes.

In this example, both an API key AND basic auth are required to access the API:

Complex authorization scenarios

This AND/OR logic along with optional ({}) security can be used in any combination to express complex authorization scenarios.

In this example, the API may be accessed with an API key AND OAuth 2.0 OR with basic authentication: