OpenAPI
OAuth2.0 Security

OAuth 2.0 Security Scheme in OpenAPI

OAuth 2.0 is a popular open authentication mechanism that supports an authentication flow allowing servers to authenticate on behalf of a user or organization.

While more generally used for authenticating clients and end-users, it is sometimes used in machine-to-machine applications, but is less popular than other security schemes due to the added complexity of the authentication flows.

OAuth 2.0 is considered more secure than other mechanisms due to its granted privileges through short-lived tokens that limit damage from intercepted tokens.

The OAuth 2.0 protocol defines multiple ways of building a request against the tokenUrl endpoint.

OAuth 2.0 Security Scheme Object in OpenAPI

The fields for an OAuth 2.0 security scheme are as follows:

FieldTypeRequiredDescription
typeStringoauth2
descriptionStringHuman-readable information. This may contain CommonMark syntax (opens in a new tab) to provide a rich description.
flowsMap[{key}, OAuth Flow Object]An object containing configuration for the available OAuth 2.0 flows. Valid keys are implicit, password, clientCredentials, and authorizationCode.
x-*ExtensionsAny number of extension fields can be added to the security scheme object to be used by tooling and vendors.

Below is an example of an OAuth 2.0 security scheme using the clientCredentials flow:


components:
securitySchemes:
clientCredentials:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://speakeasy.bar/oauth2/token/
scopes: {}
security:
- clientCredentials: []

OAuth Flow Object in OpenAPI

The value of the flows object is a map of OAuth 2.0 flow objects.

The four supported OAuth 2.0 flows are:

Each flow object has its own configuration parameters, as described below.

Implicit Flow Object in OpenAPI

The Implicit flow is generally used for single-page applications that can't keep a client secret as all the application code is available to the user.

FieldTypeRequiredDescription
authorizationUrlStringThe authorization URL to be used for this flow.
refreshUrlStringThe URL to be used for refreshing the token. No refresh URL means the token is not refreshable.
scopesMap[String, String]The available scopes for the OAuth 2.0 flow, with a description for each scope. Although the specification requires this field, it can be an empty object.
x-*ExtensionsAny number of extension fields can be added to an OAuth Flow object to be used by tooling and vendors to add additional metadata and functionality to the OpenAPI Specification.

The example below shows an OAuth 2.0 security scheme using the implicit flow:


components:
securitySchemes:
implicit:
type: oauth2
flows:
implicit:
authorizationUrl: https://speakeasy.bar/oauth2/authorize/
refreshUrl: https://speakeasy.bar/oauth2/refresh/
scopes:
read: Grants read access
write: Grants write access

Password Flow Object in OpenAPI

The Password flow is generally used for trusted first-party clients that can securely store the client secret.

FieldTypeRequiredDescription
tokenUrlStringThe token URL to be used for this flow.
refreshUrlStringThe URL to be used for refreshing the token. No refresh URL means the token is not refreshable.
scopesMap[String, String]The available scopes for the OAuth 2.0 flow, with a description for each scope. Although the specification requires this field, it can be an empty object.
x-*ExtensionsAny number of extension fields can be added to an OAuth Flow object to be used by tooling and vendors to add additional metadata and functionality to the OpenAPI Specification.

The example below shows an OAuth 2.0 security scheme using the password flow:


components:
securitySchemes:
password:
type: oauth2
flows:
password:
tokenUrl: https://speakeasy.bar/oauth2/token/
refreshUrl: https://speakeasy.bar/oauth2/refresh/
scopes:
read: Grants read access
write: Grants write access

Client Credentials Flow Object in OpenAPI

The Client Credentials flow is generally used for machine-to-machine communication where a specific user's permission is not required.

FieldTypeRequiredDescription
tokenUrlStringThe token URL to be used for this flow.
refreshUrlStringThe URL to be used for refreshing the token. No refresh URL means the token is not refreshable.
scopesMap[String, String]The available scopes for the OAuth 2.0 flow, with a description for each scope. Although the specification requires this field, it can be an empty object.
x-*ExtensionsAny number of extension fields can be added to an OAuth Flow object to be used by tooling and vendors to add additional metadata and functionality to the OpenAPI Specification.

The example below shows an OAuth 2.0 security scheme using the clientCredentials flow:


components:
securitySchemes:
clientCredentials:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://speakeasy.bar/oauth2/token/
refreshUrl: https://speakeasy.bar/oauth2/refresh/
scopes:
read: Grants read access
write: Grants write access

Authorization Code Flow Object in OpenAPI

The Authorization Code flow is generally used for server-side applications where the client secret can be securely stored.

FieldTypeRequiredDescription
authorizationUrlStringThe authorization URL to be used for this flow.
tokenUrlStringThe token URL to be used for this flow.
refreshUrlStringThe URL to be used for refreshing the token. No refresh URL means the token is not refreshable.
scopesMap[String, String]The available scopes for the OAuth 2.0 flow, with a description for each scope. Although the specification requires this field, it can be an empty object.
x-*ExtensionsAny number of extension fields can be added to an OAuth Flow object to be used by tooling and vendors to add additional metadata and functionality to the OpenAPI Specification.

The example below shows an OAuth 2.0 security scheme using the authorizationCode flow:


components:
securitySchemes:
authorizationCode:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://speakeasy.bar/oauth2/authorize/
tokenUrl: https://speakeasy.bar/oauth2/token/
refreshUrl: https://speakeasy.bar/oauth2/refresh/
scopes:
read: Grants read access
write: Grants write access

OAuth 2.0 Security Scheme With Multiple Flows in OpenAPI

You can define an OAuth 2.0 security scheme with multiple flows by specifying each flow in the flows object.

The example below shows an OAuth 2.0 security scheme using the authorizationCode and clientCredentials flows:


components:
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://speakeasy.bar/oauth2/authorize/
tokenUrl: https://speakeasy.bar/oauth2/token/
refreshUrl: https://speakeasy.bar/oauth2/refresh/
scopes:
read: Grants read access
write: Grants write access
clientCredentials:
tokenUrl: https://speakeasy.bar/oauth2/token/
refreshUrl: https://speakeasy.bar/oauth2/refresh/
scopes:
read: Grants read access
write: Grants write access
security:
- oauth2: []

Scopes in OAuth 2.0 in OpenAPI

Scopes are used to define the permissions that a client has when accessing a resource. The scopes are defined in the scopes object of the OAuth flow object.

The scopes required for a specific operation are defined in the security object of the operation.

The example below shows an OAuth 2.0 security scheme with scopes:


components:
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://speakeasy.bar/oauth2/authorize/
tokenUrl: https://speakeasy.bar/oauth2/token/
refreshUrl: https://speakeasy.bar/oauth2/refresh/
scopes:
read: Grants read access
write: Grants write access
paths:
/drinks:
get:
operationId: listDrinks
summary: Get a list of drinks
# Operation requires read scope
security:
- oauth2:
- read