OAuth 2.0

OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server. GitHub, Google, and Facebook APIs notably use it. OAuth relies on authentication scenarios called flows, which allow the resource owner (user) to share the protected content from the resource server without sharing their credentials. For that purpose, an OAuth 2.0 server issues access tokens that the client applications can use to access protected resources on behalf of the resource owner. For more information about OAuth 2.0, see oauth.net and RFC 6749.

Flows

The flows (also called grant types) are scenarios an API client performs to get an access token from the authorization server. OAuth 2.0 provides several flows suitable for different types of API clients:

Authorization code – The most common flow, mostly used for server-side and mobile web applications. This flow is similar to how users sign up into a web application using their Facebook or Google account.
Implicit – This flow requires the client to retrieve an access token directly. It is useful in cases when the user’s credentials cannot be stored in the client code because they can be easily accessed by the third party. It is suitable for web, desktop, and mobile applications that do not include any server component.
Resource owner password credentials (or just password) – Requires logging in with a username and password. Since in that case the credentials will be a part of the request, this flow is suitable only for trusted clients (for example, official applications released by the API provider).
Client Credentials – Intended for the server-to-server authentication, this flow describes an approach when the client application acts on its own behalf rather than on behalf of any individual user. In most scenarios, this flow provides the means to allow users specify their credentials in the client application, so it can access the resources under the client’s control.

Describing OAuth 2.0 Using OpenAPI

To describe an API protected using OAuth 2.0, first, add a security scheme with type: oauth2 to the global components/securitySchemes section. Then add the security key to apply security globally or to individual operations:

1
# Step 1 - define the security scheme
2
components:
3
  securitySchemes:
4
    oAuthSample:    # <---- arbitrary name
5
      type: oauth2
6
      description: This API uses OAuth 2 with the implicit grant flow. [More info](https://api.example.com/docs/auth)
7
      flows:
8
        implicit:   # <---- OAuth flow(authorizationCode, implicit, password or clientCredentials)
9
          authorizationUrl: https://api.example.com/oauth2/authorize
10
          scopes:
11
            read_pets: read your pets
12
            write_pets: modify pets in your account
13

14
# Step 2 - apply security globally...
15
security:
16
  - oAuthSample:
17
    - write_pets
18
    - read_pets
19

20
# ... or to individual operations
21
paths:
22
  /pets:
23
    patch:
24
      summary: Add a new pet
25
      security:
26
        - oAuthSample:
27
          - write_pets
28
          - read_pets
29
      ...

The flows keyword specifies one or more named flows supported by this OAuth 2.0 scheme. The flow names are:

authorizationCode – Authorization Code flow (previously called accessCode in OpenAPI 2.0)
implicit – Implicit flow
password – Resource Owner Password flow
clientCredentials – Client Credentials flow (previously called application in OpenAPI 2.0)

The flows object can specify multiple flows, but only one of each type. Each flow contains the following information:

Field Name	Description	Applies to flows
Field Name	Description	`authorizationCode`	`implicit`	`password`	`clientCredentials`
`authorizationUrl`	The authorization URL to use for this flow. Can be relative to the API server URL.	+	+	-	-
`tokenUrl`	The token URL to use for this flow. Can be relative to the API server URL.	+	-	+	+
`refreshUrl`	Optional. The URL to be used for obtaining refresh tokens. Can be relative to the API server URL.	+	+	+	+
`scopes`	The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.	+	+	+	+

About Scopes

With OpenAPI 3.0, a user can grant scoped access to their account, which can vary depending on the operation the client application wants to perform. Each OAuth access token can be tagged with multiple scopes. Scopes are access rights that control whether the credentials a user provides allow to perform the needed call to the resource server. They do not grant any additional permissions to the client except for those it already has. Note: In the authorization code and implicit flows, the requested scopes are listed on the authorization form displayed to the user. To apply the scopes, you need to perform two steps:

Define all supported scopes in your OAuth security definition in the components/securitySchemes section:

1
components:
2
  securitySchemes:
3
    oAuthSample:
4
      type: oauth2
5
      flows:
6
        implicit:
7
          authorizationUrl: https://api.example.com/oauth2/authorize
8
          scopes:
9
            read_pets: read pets in your account
10
            write_pets: modify pets in your account

List the scopes required by each operation in the security section of that operation:

1
paths:
2
  /pets/{petId}:
3
    patch:
4
      summary: Updates a pet in the store
5
      security:
6
        - oAuthSample: [write_pets]
7
      ...

If all API operations require the same scopes, you can add security on the root level of the API definition instead:

1
security:
2
  - oAuthSample: [write_pets]

No Scopes

Scopes are optional, and your API may not use any. In this case, specify an empty object {} in the scopes definition, and an empty list of scopes [] in the security section:

1
components:
2
  securitySchemes:
3
    oAuthNoScopes:
4
      type: oauth2
5
      flows:
6
        implicit:
7
          authorizationUrl: https://api.example.com/oauth2/authorize
8
          scopes: {} # <-----
9

10
security:
11
  - oAuthNoScopes: [] # <-----

Relative Endpoint URLs

In OpenAPI 3.0, authorizationUrl, tokenUrl and refreshUrl can be specified relative to the API server URL. This is handy if these endpoints are on same server as the rest of the API operations.

1
servers:
2
  - url: https://api.example.com/v2
3

4
components:
5
  securitySchemes:
6
    oauth2sample:
7
      type: oauth2
8
      flows:
9
        authorizationCode:
10
          authorizationUrl: /oauth/authorize # <-----
11
          tokenUrl: /oauth/token # <-----
12
          scopes: ...

Relative URLs are resolved according to RFC 3986. In the example above, the endpoints will be resolved to:

authorizationUrl: https://api.example.com/oauth/authorize

tokenUrl: https://api.example.com/oauth/token

Security Scheme Examples

Authorization Code Flow

The authorization flow uses authorizationUrl, tokenUrl and optional refreshUrl. Here is an example for Slack API:

1
components:
2
  securitySchemes:
3
    oAuth2AuthCode:
4
      type: oauth2
5
      description: For more information, see https://api.slack.com/docs/oauth
6
      flows:
7
        authorizationCode:
8
          authorizationUrl: https://slack.com/oauth/authorize
9
          tokenUrl: https://slack.com/api/oauth.access
10
          scopes:
11
            users:read: Read user information
12
            users:write: Modify user information
13
            im:read: Read messages
14
            im:write: Write messages
15
            im:history: Access the message archive
16
            search:read: Search messages, files, and so on
17
            # etc.

Implicit Flow

implicit flow defines authorizationUrl that is used to obtain the access token from the authorization server. Here is an example:

1
components:
2
  securitySchemes:
3
    oAuth2Implicit:
4
      type: oauth2
5
      description: For more information, see https://developers.getbase.com/docs/rest/articles/oauth2/requests
6
      flows:
7
        implicit:
8
          authorizationUrl: https://api.getbase.com/oauth2/authorize
9
          scopes:
10
            read: Grant read-only access to all your data except for the account and user info
11
            write: Grant write-only access to all your data except for the account and user info
12
            profile: Grant read-only access to the account and user info only

Resource Owner Password Flow

The password flow uses tokenUrl and optional refreshUrl. Here is an example:

1
components:
2
  securitySchemes:
3
    oAuth2Password:
4
      type: oauth2
5
      description: See https://developers.getbase.com/docs/rest/articles/oauth2/requests
6
      flows:
7
        password:
8
          tokenUrl: https://api.getbase.com/oauth2/token
9
          scopes:
10
            read: Grant read-only access to all your data except for the account and user info
11
            write: Grant write-only access to all your data except for the account and user info
12
            profile: Grant read-only access to the account and user info only

Client Credentials Flow

The clientCredentials flow uses tokenUrl and optional refreshUrl. Here is an example for Getty Images API:

1
components:
2
  securitySchemes:
3
    oAuth2ClientCredentials:
4
      type: oauth2
5
      description: See http://developers.gettyimages.com/api/docs/v3/oauth2.html
6
      flows:
7
        clientCredentials:
8
          tokenUrl: https://api.gettyimages.com/oauth2/token/
9
          scopes: {} # Getty Images does not use scopes

Multiple Flows

Below is an example of the OAuth 2.0 security definition that supports multiple flows. The clients can use any of these flows.

1
components:
2
  securitySchemes:
3
    oAuth2:
4
      type: oauth2
5
      description: For more information, see https://developers.getbase.com/docs/rest/articles/oauth2/requests
6
      flows:
7
        implicit:
8
          authorizationUrl: https://api.getbase.com/oauth2/authorize
9
          scopes:
10
            read: Grant read-only access to all your data except for the account and user info
11
            write: Grant write-only access to all your data except for the account and user info
12
            profile: Grant read-only access to the account and user info only
13
        password:
14
          tokenUrl: https://api.getbase.com/oauth2/token
15
          scopes:
16
            read: Grant read-only access to all your data except for the account and user info
17
            write: Grant write-only access to all your data except for the account and user info
18
            profile: Grant read-only access to the account and user info only

Frequently Asked Questions

Should I additionally define authorizationUrl and tokenUrl as API operations?

authorizationUrl is not an API endpoint but a special web page that requires user input. So, it cannot be described using OpenAPI. Still, you can describe tokenUrl if you need it.

Should authorizationUrl and tokenUrl include query string parameters, such as grant_type, client_id and others?

The OpenAPI Specification does not state this, so it is up to you and the tools you use.

Did not find what you were looking for? Ask the community Found a mistake? Let us know