Security Scheme Objects in OpenAPI

Security scheme objects are defined in the Components Object under the securitySchemes field. Each security scheme object has a unique key. Security Requirement Objects elsewhere in the document reference security scheme objects by their keys.

The following example requires a basic authentication scheme to access the /drinks endpoint:

paths:
  /drinks:
    get:
      security:
        - MyScheme17: []
components:
  securitySchemes:
    MyScheme17:
      type: http
      scheme: basic

The type field is the overall category of authentication. The value of type determines the other fields the security object needs.

To decide which authentication type to choose, see our article OpenAPI Tips - How to Handle Auth (opens in a new tab).

OpenAPI-Supported Authentication Types

The following authentication types are supported in the OpenAPI Specification:

OpenAPI Example Security Scheme Schema

Below is an example security schemes object with every possible field besides extensions.

components:
  securitySchemes:
    # apiKey ------------
    auth1:
      description: Recommended authenticator
      type: apiKey
      in: query
      name: key

    auth2:
      type: apiKey
      in: header
      name: X-API-Key

    auth3:
      type: apiKey
      in: cookie
      name: key

    # http ------------
    auth4:
      type: http
      scheme: basic

    auth5:
      type: http
      scheme: bearer
      bearerFormat: JWT

    auth6:
      type: http
      scheme: digest # not supported by Speakeasy

    # mutualTLS ------------
    auth7:
      type: mutualTLS # not supported by Speakeasy

    # openIdConnect ------------
    auth8:
      type: openIdConnect
      openIdConnectUrl: https://example.com/openidconfig.json

    # oauth2 ------------
    auth9:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            read: Grants read access
            write: Grants write access
          authorizationUrl: https://test.com/oauth/authorize
          tokenUrl: https://test.com/oauth/token
          refreshUrl: https://test.com/oauth/refresh
        clientCredentials:
          scopes:
            read: Grants read access
            write: Grants write access
          tokenUrl: https://test.com/oauth/token
          refreshUrl: https://test.com/oauth/refresh
        implicit:
          scopes:
            read: Grants read access
            write: Grants write access
          authorizationUrl: https://test.com/oauth/authorize
          refreshUrl: https://test.com/oauth/refresh
        password:
          scopes:
            read: Grants read access
            write: Grants write access
          tokenUrl: https://test.com/oauth/token
          refreshUrl: https://test.com/oauth/refresh