Skip to content
Status

Security

OAuth 2 in OpenAPI

The OAuth 2 security scheme in OpenAPI

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

While more generally used for authenticating end users (for example, logging the user in with Facebook), OAuth 2 is also used for machine-to-machine flows where a whole application authenticates itself with the API (for example, connecting Shopify to Xero).

OAuth 2 is considered more secure than other mechanisms due to its granting privileges through short-lived tokens that limit damage from intercepted tokens. Tokens that can only be used for a day can only cause damage for a day. A well-built API won’t allow short-lived tokens to be used to escalate privileges (for example, to change a user’s password), so less damage can be done while the token is valid.

The OAuth 2 protocol defines multiple ways of building a request against the tokenUrl endpoint and supports multiple flows at once, so that developers can set up different types of integration for the same API.

Defining the OAuth 2 security scheme

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

Field
type
Type
String
Description
oauth2
Required
✅
description
Type
String
Description
Human-readable information. This may contain CommonMark syntax to provide a rich description.
Required
flows
Type
Map[{key}, OAuth Flow Object]
Description
An object containing configuration for the available OAuth 2 flows. Valid keys are implicit, password, clientCredentials, authorizationCode, and deviceAuthorization (OpenAPI v3.2.0+).
Required
✅
x-*
Description
Any number of extension fields can be added to the Security Scheme Object to be used by tooling and vendors.
Required

The following example shows an OAuth 2 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
security:
  - clientCredentials: []

Defining OAuth flows

The value of the OAuth Flows Object is a map of OAuth Flow Objects.

The OpenAPI Specification supports the following OAuth Flow Objects:

Each OAuth Flow Object has its own configuration parameters, so let’s look at them individually.

The Client Credentials flow

The Client Credentials flow is generally used for machine-to-machine communication that doesn’t require a specific user’s permission and context. Think of an entire application integrating with a whole other application, to sync billing information or other organization-wide information.

Field
tokenUrl
Type
String
Description
The token URL to be used for this flow.
Required
✅
refreshUrl
Type
String
Description
The URL to be used for refreshing the token. No refresh URL means the token is not refreshable.
Required
scopes
Type
Map[String, String]
Description
The available scopes for the OAuth 2 flow, with a description for each scope. Although the specification requires this field, it can be an empty object.
Required
✅
x-*
Description
Any 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.
Required

The example below shows an OAuth 2 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

The Authorization Code flow

The Authorization Code flow is generally used for server-side applications that can safely store the client secret.

Field
authorizationUrl
Type
String
Description
The authorization URL to be used for this flow.
Required
✅
tokenUrl
Type
String
Description
The token URL to be used for this flow.
Required
✅
refreshUrl
Type
String
Description
The URL to be used for refreshing the token. No refresh URL means the token is not refreshable.
Required
scopes
Type
Map[String, String]
Description
The available scopes for the OAuth 2 flow, with a description for each scope. Although the specification requires this field, it can be an empty object.
Required
✅
x-*
Description
Any 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.
Required

The following example shows an OAuth 2 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

The Password flow

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

Field
tokenUrl
Type
String
Description
The token URL to be used for this flow.
Required
✅
refreshUrl
Type
String
Description
The URL to be used for refreshing the token. No refresh URL means the token is not refreshable.
Required
scopes
Type
Map[String, String]
Description
The available scopes for the OAuth 2 flow, with a description for each scope. Although the specification requires this field, it can be an empty object.
Required
✅
x-*
Description
Any 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.
Required

The following example shows an OAuth 2 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

The Implicit flow

The Implicit flow is generally used for browser or client-side applications that can’t keep a client secret because, in a browser, all code and data are available to the user. Although it was popular for a while, the IETF’s OAuth working group recommends not using the implicit grant anymore.

Field
authorizationUrl
Type
String
Description
The authorization URL to be used for this flow.
Required
✅
refreshUrl
Type
String
Description
The URL to be used for refreshing the token. No refresh URL means the token is not refreshable.
Required
scopes
Type
Map[String, String]
Description
The available scopes for the OAuth 2 flow, with a description for each scope. Although the specification requires this field, it can be an empty object.
Required
✅
x-*
Description
Any 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.
Required

The following example shows an OAuth 2 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

Using OAuth 2 with multiple flows

If needed, you can use multiple OAuth 2 flows in a single API by describing each of the flows in the OAuth Flows Object.

Consider the following example, which uses both the authorizationCode flow and the clientCredentials flow:

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: []

If you have an API in which different endpoints support different flows, split the endpoints into different securitySchemes.

Consider this example, where the whole API is secured by clientCredentials except for the /profile endpoint, which requires authorizationCode:

security:
  - MachineAuth: []


paths:
  "/profile":
    security:
      - UserAuth: []


components:
  securitySchemes:
    UserAuth:
      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


    MachineAuth:
      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

Scopes in OAuth 2

In an API, scopes define more granular permissions or access controls. APIs can use very generic scopes, like read and write.

Other APIs focus on different resources:

  • invoices
  • customers
  • orders

Some go even further and break scopes into resources and actions:

  • invoices:read
  • invoices:write
  • invoices:delete
  • customers:read
  • customers:write
  • customers:delete
  • orders:read
  • orders:write
  • orders:delete

You can use detailed scopes not only to ensure that users don’t see anything they shouldn’t, but to limit accidental data loss when misconfigured applications go rogue.

Scopes are defined in the scopes field of the OAuth Flow Object, and the scopes required for a specific operation are defined in the Security Requirement Object (the security field) for that operation:

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:
            'drinks:read': Grants read access to drinks resource
            'drinks:write': Grants write access to drinks resource
paths:
  /drinks:
    get:
      operationId: listDrinks
      summary: Get a list of drinks
      security:
        - oauth2:
            - drinks:read

Using OAuth 2 without scopes

Scopes are optional, and an API may not use them at all. To create an API without scopes, define scopes as an empty object {} and define the security requirement (for example, oauth2 below) as an empty list of 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: {}
security:
  - oauth2: []

OAuth 2.1 and Device Authorization

OAuth 2.1 is a simplified version of OAuth 2 that combines its best practices and removes the less secure flows. There aren’t many changes directly related to OpenAPI, so the existing structure works fine for both versions.

For more information on the changes and improvements made in OAuth 2.1, refer to the OAuth 2.1 specification.

The Device Authorization flow

The Device Authorization flow (also called the Device Authorization grant) is designed for devices with limited input capabilities, such as smart TVs, kiosks, and IoT devices. Instead of entering credentials directly, the device displays a code that the user enters on a separate device with a full browser. OpenAPI v3.2.0 adds support for this flow using the deviceAuthorization key.

For more information on the Device Authorization grant, refer to the specification for the OAuth 2.0 Device Authorization grant.

Field
deviceAuthorizationUrl
Type
String
Description
The device authorization URL to be used for this flow.
Required
✅
tokenUrl
Type
String
Description
The token URL to be used for this flow.
Required
✅
refreshUrl
Type
String
Description
The URL to be used for refreshing the token. No refresh URL means the token is not refreshable.
Required
scopes
Type
Map[String, String]
Description
The available scopes for the OAuth 2 flow, with a description for each scope. Although the specification requires this field, it can be an empty object.
Required
✅
x-*
Description
Any 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.
Required

The following example shows an OAuth 2 security scheme using the deviceAuthorization flow:

components:
  securitySchemes:
    deviceAuth:
      type: oauth2
      flows:
        deviceAuthorization:
          deviceAuthorizationUrl: https://speakeasy.bar/oauth2/device
          tokenUrl: https://speakeasy.bar/oauth2/token
          refreshUrl: https://speakeasy.bar/oauth2/refresh
          scopes:
            read: Grants read access
            write: Grants write access
security:
  - deviceAuth: []

OAuth 2.0 metadata discovery

OpenAPI v3.2.0 adds the oauth2MetadataUrl field to the OAuth Flow Object. This field provides a URL pointing to the OAuth 2.0 Authorization Server Metadata document (RFC 8414), enabling clients to automatically discover OAuth 2.0 endpoint configuration.

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://speakeasy.bar/oauth2/authorize
          tokenUrl: https://speakeasy.bar/oauth2/token
          oauth2MetadataUrl: https://speakeasy.bar/.well-known/oauth-authorization-server
          scopes:
            read: Grants read access
            write: Grants write access