OpenAPI Security Schemes Explained

Anton Okolelov

5 min read

·

Jun 21, 2026

--

Listen

Share

Press enter or click to view image in full size

The OpenAPI specification can seem quite complex. It is a large document with many details and edge cases to keep in mind, especially if you are not using dedicated editing tools.

One area that often causes confusion is how to describe authentication and authorization requirements for an API.

Most APIs use some form of security: an API key passed in a header or query parameter, HTTP authentication, OAuth 2.0, OpenID Connect, or mutual TLS with a client certificate.

In OpenAPI, this is described in two steps:

1. Define a Security Scheme component, specifying its type and the required parameters (see below).
2. Reference that scheme from the security field, either globally or for a specific operation.

Defining a Security Scheme component

First, in the components section, you need to describe a Security Scheme object (see the specification). At a minimum, you need to give the component a name — this name will be used in other parts of the document — and specify its type, along with the parameters required for that particular type.

For example, if you are simply using basic HTTP authentication, it will look like this:

components:
  securitySchemes:
    basicHttpAuthentication: # a name
      type: http
      scheme: basic

There can be several components in securitySchemes if your API supports multiple authentication methods.

Later, we will describe each type in detail: API Keys, HTTP Authentication, Mutual TLS, OAuth 2.0, and OpenID Connect. For now, let’s look at how to use this component in the document.

Using the component

Once the component has been defined, it can be used either globally across the entire document or for a specific operation.

Globally:

security:
  - basicHttpAuthentication: []

In the security section, we specify an object or objects. Each such object is a key-value mapping (see the specification), where the key is the name of the scheme from components, and the value is an array. For oauth2 and openIdConnect, this array contains the required scopes, which we will discuss below. If no specific scopes are needed, the array can be empty. For other types, [] is usually used.

OpenAPI 3.1.1 also states that for other types, the array may contain roles, but these roles are not defined or transmitted in-band by the specification itself.

Here is a complete example:

openapi: 3.1.0
info:
  title: My API
  description: |
     some description
  version: 1.0.0
security: # using components globally
  - basicHttpAuthentication: []
components:
  securitySchemes: #define components
    basicHttpAuthentication:
      type: http
      scheme: basic

You can list several alternative components:

security:
  - basicHttpAuthentication: []
  - oauth2Profiles:
    - board:read
    - board:write

If the document can be used both with and without authorization, you can specify an empty object {} as an alternative option:

security:
  - {}
  - basicHttpAuthentication: []
  - oauth2Profiles:
    - board:read
    - board:write

Finally, if you want the client to use two methods at the same time, you can combine them into a single object with multiple keys. Notice the missing - before oauth2Profiles:

security:
  - mutualTLS: []
    oauth2Profiles:
      - 'board:read'
      - 'board:write'

Elements of the security array are OR conditions, while multiple keys inside a single object are AND conditions.

Security can be defined not only for the entire document, but also for a specific operation, where it can override the global definition:

openapi: 3.1.0
info:
  title: My API
  description: |
     some description
  version: 1.0.0
security: # using components globally
  - basicHttpAuthentication: []
paths:
  /public-endpoint:
    get:
      security: [] # no security requirements for GET /public-endpoint

Now let’s look at all the types of security schemes that can be defined in components.

API key (type: apiKey)

If you want to describe security using an API key, you must provide two parameters: name and in.

in specifies where the key will be passed: as a query parameter, header, or cookie. name is the name of that query parameter, header, or cookie respectively.

components:
  securitySchemes:
    apiKey:
      description: API key
      type: apiKey
      name: X-API-Key
      in: header

HTTP Authentication (type: http)

This refers to the standard Authorization header defined in RFC 7235.

For example:

Authorization: Bearer abc123abcdf100500asdf

Along with the http type, you must also specify the scheme field, such as basic, bearer, digest, or another value. For bearer, you can also specify bearerFormat. For example:

components:
  securitySchemes:
    httpAuthWithBearer:
      description: Some description
      type: http
      scheme: bearer
      bearerFormat: JWT # A hint to identify how the bearer token is formatted

Mutual TLS (type: mutualTLS)

Mutual TLS is a TLS variant where not only does the client verify the server’s certificate, but the server also verifies the client’s certificate. If you use it, simply specify the type and any necessary description, if required. This type is supported in OpenAPI 3.1+.

components:
  securitySchemes:
    mutualTLSAuth:
      description: Some description
      type: mutualTLS

OAuth2 (type: oauth2)

For OAuth2, you need to specify flows, which are OAuth authorization variants.

The available flows are as follows (see the specification):

authorizationCode — the user opens an authorization page, logs in, gives consent, and then the application receives a code and exchanges it for a token. For authorizationCode, you must also specify authorizationUrl and tokenUrl.

clientCredentials — one backend service obtains a token in order to access another backend service. You must specify tokenUrl.

password — a legacy flow where the application directly receives the user’s login and password and exchanges them for a token. You must specify tokenUrl.

implicit — an older variant where the token was returned directly through the browser without exchanging an authorization code for a token. You must specify authorizationUrl.

deviceAuthorization — available only in OpenAPI 3.2 — is used for devices where entering a login and password is inconvenient. You must specify deviceAuthorizationUrl and tokenUrl.

For each flow, you must specify scopes; this is a required field.

It looks roughly like this:

components:
  securitySchemes:
    oauth2Profiles:
      type: oauth2
      description: OAuth 2.0 authorization
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            board:read: Read boards
            board:write: Create and update boards

When using this component in the document, you can specify which exact scopes apply. In this case, GET /boards requires the board:read scope:

paths:
  /boards:
    get:
      operationId: listBoards
      security:
        - oauth2Profiles:
            - board:read

Starting with OpenAPI 3.2, it is also possible to define oauth2MetadataUrl — a URL that describes where the authorization endpoint, token endpoint, and other endpoints are located (RFC 8414).

Here is an example of a full document:

openapi: 3.2.0

info:
  title: OAuth Example
  version: 1.0.0paths:
  /me:
    get:
      security:
        - oauth:
            - profile
      responses:
        '200':
          description: OKcomponents:
  securitySchemes:
    oauth:
      type: oauth2
      oauth2MetadataUrl: https://auth.example.com/.well-known/oauth-authorization-server
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            profile: Read user profile

Press enter or click to view image in full size

OpenID Connect (OIDC) (type: openIdConnect)

OIDC is used when a user signs in to an application through Google, Microsoft, or similar providers.

For this type of security, you need to specify openIdConnectUrl.

components:
  securitySchemes:
    googleOidc:
      type: openIdConnect
      openIdConnectUrl: https://accounts.google.com/.well-known/openid-configuration

Useful links

OpenAPI Specification — https://spec.openapis.org/oas/
OpenAPI GUI Editor (IDE plugin) — https://plugins.jetbrains.com/plugin/27118-openapi-gui-editor