Authentication

Swagger 2.0 lets you define the following authentication types for an API:

Basic authentication
API key (as a header or a query string parameter)
OAuth 2 common flows (authorization code, implicit, resource owner password credentials, client credentials)

Follow the links above for examples specific to these authentication types, or continue reading to learn how to describe authentication in general.

Authentication is described by using the securityDefinitions and security keywords. You use securityDefinitions to define all authentication types supported by the API, then use security to apply specific authentication types to the whole API or individual operations.

The securityDefinitions section is used to define all security schemes (authentication types) supported by the API. It is a name->definition map that maps arbitrary names to the security scheme definitions. Here, the API supports three security schemes named BasicAuth, ApiKeyAuth and OAuth2, and these names will be used to refer to these security schemes from elsewhere:

1
securityDefinitions:
2
  BasicAuth:
3
    type: basic
4
  ApiKeyAuth:
5
    type: apiKey
6
    in: header
7
    name: X-API-Key
8
  OAuth2:
9
    type: oauth2
10
    flow: accessCode
11
    authorizationUrl: https://example.com/oauth/authorize
12
    tokenUrl: https://example.com/oauth/token
13
    scopes:
14
      read: Grants read access
15
      write: Grants write access
16
      admin: Grants read and write access to administrative information

Each security scheme can be of type:

basic for Basic authentication
apiKey for an API key
oauth2 for OAuth 2

Other required properties depend on the security type. For details, check the Swagger Specification or our examples for Basic auth and API keys.

After you have defined the security schemes in securityDefinitions, you can apply them to the whole API or individual operations by adding the security section on the root level or operation level, respectively. When used on the root level, security applies the specified security schemes globally to all API operations, unless overridden on the operation level.

In the following example, the API calls can be authenticated using either an API key or OAuth 2. The ApiKeyAuth and OAuth2 names refer to the security schemes previously defined in securityDefinitions.

1
security:
2
  - ApiKeyAuth: []
3
  - OAuth2: [read, write]

Global security can be overridden in individual operations to use a different authentication type, different OAuth 2 scopes, or no authentication at all:

1
paths:
2
/billing_info:
3
  get:
4
    summary: Gets the account billing info
5
    security:
6
      - OAuth2: [admin]   # Use OAuth with a different scope
7
    responses:
8
      200:
9
        description: OK
10
      401:
11
        description: Not authenticated
12
      403:
13
        description: Access token does not have the required scope
14

15
/ping:
16
  get:
17
    summary: Checks if the server is running
18
    security: []   # No security
19
    responses:
20
      200:
21
        description: Server is up and running
22
      default:
23
        description: Something is wrong

Using Multiple Authentication Types

Some REST APIs support several authentication types. The security section lets you combine the security requirements using logical OR and AND to achieve the desired result. security uses the following logic:

1
security:    # A OR B
2
  - A
3
  - B
4

5
security:    # A AND B
6
  - A
7
    B
8

9
security:    # (A AND B) OR (C AND D)
10
  - A
11
    B
12
  - C
13
    D

That is, security is an array of hashmaps, where each hashmap contains one or more named security schemes. Items in a hashmap are combined using logical AND, and array items are combined using logical OR. Security schemes combined via OR are alternatives – any one can be used in the given context. Security schemes combined via AND must be used simultaneously in the same request. Here, we can use either Basic authentication or an API key:

1
security:
2
  - basicAuth: []
3
  - apiKey: []

Here, the API requires a pair of API keys to be included in requests:

1
security:
2
  - apiKey1: []
3
    apiKey2: []

Here, we can use either OAuth 2 or a pair of API keys:

1
security:
2
  - oauth2: [scope1, scope2]
3
  - apiKey1: []
4
    apiKey2: []

FAQ

What does [ ] mean in “securitySchemeName: [ ]”?

[] is a YAML/JSON syntax for an empty array. The Swagger Specification requires that items in the security array specify a list of required scopes, as in:

1
security:
2
  - securityA: [scopeA1, scopeA2]
3
  - securityB: [scopeB1, scopeB2]

Scopes are only used with OAuth 2, so the Basic and API key security items use an empty array instead.

1
security:
2
  - oauth2: [scope1, scope2]
3
  - BasicAuth: []
4
  - ApiKeyAuth: []

Reference

securityDefinitions

security

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