OpenAPI
Security Schemes

Security Scheme Object

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. For example:


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.

Below are the string fields that do not depend on type and can be used in any security scheme.

FieldRequiredDescription
typeThe type of the security scheme.

Allowed values: apiKey, http, mutualTLS, oauth2, or openIdConnect.

mutualTLS is for OpenAPI version 3.1 only.
descriptionHuman-readable information. CommonMark syntax (opens in a new tab) may be used.
x-...Extension fields

To decide which authentication type to choose, please review this article (opens in a new tab).

Below are the fields that are required for each value of type. They are all strings, except for the OAuth flows, which are discussed in the next section.

FieldApplies toDescription
in: (query, header, or cookie)type: apiKeyThe location of the API key in the request.
name:type: apiKeyThe name of the key parameter in the location.
scheme: (basic, bearer, or digest)type: httpThe name of the HTTP authorization scheme to be used in the Authorization header. More values (opens in a new tab) are theoretically allowed, but not supported in practice.
bearerFormat:type: http
scheme: bearer
A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
_type: mutualTLSNo extra fields are required. Mutual TLS means the server will ask the client for a public security certificate after the server has sent its certificate.
openIdConnectUrl: https://...type: openIdConnectUsed to discover configuration values. The URL must point to a JSON OpenID Connect Discovery document.
flows:
  authorizationCode: ...
  clientCredentials: ...
  implicit: ...
  password: ...
type: oauth2The flows object contains four possible authentication flow objects. At least one must be present and you can use all four. The structure of a flow is detailed in the next section.

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