Security in OpenAPI

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

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

OpenAPI divides security into two parts:

• Security schemes, which are defined as reusable components.
• Security requirements, which invoke the reusable security schemes either across the whole API or within specific operations.

The following simple example of an API key demonstrates the basic security structure defined in the OpenAPI Specification:

Supported security schemes

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

The OpenAPI Specification 3.1 supports the following security schemes:

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

Once you’ve defined an API’s security schemes, you can reference them in the security section of the OpenAPI document or at the operation level.

The 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 the 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: The security is only applied to the operation, overriding any global-level security.

The following example demonstrates how to describe security at both levels:

The security and securitySchemes sections (representing the Security Object and Security Scheme Object, respectively) are most important in this example.

Working with security requirements

Depending on the API, security requirements can be simple or complex. The following examples illustrate how to work with security requirements in OpenAPI.

Simple API security

All the operations in an API may require an API key for access. You can define this requirement 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. You can use the security section to define the security requirements either for the entire API or for specific operations.

Multiple security schemes

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

In the following example, the API can be accessed with either an API key or OAuth 2.0. OAuth 2.0 allows for more granular access control using the concept of scopes, which can be defined in the securitySchemes section and referenced 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 the scopes or roles required for the security scheme.

For example, the following Security Requirement Object indicates that the read and write scopes are required for the oauth2 security scheme:

Disabling security requirements for specific operations

You can disable security 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

You can make security 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:

Optional security for specific operations

Similarly, you can make security 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

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

You can use this AND/OR logic, along with optional ({}) security, 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: