# focus(3:16)
paths:
  /drinks:
    get:
      operationId: listDrinks
      summary: Get a list of drinks
      security:
        - apiKey: [] # Can be access with an API key, or...
        - oauth2: # an oauth2 token which has the read scope
            - read
    post:
      operationId: createDrink
      summary: Create a new drink
      security:
        - apiKey: [] # Can be accessed with an API key, or...
        - oauth2: # an oauth2 token which has the write scope
            - write

components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: Speakeasy-API-Key
      in: header
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Read access to the API
            write: Write access to the API
```

## Security requirement scopes or roles in OpenAPI

When defining an OAuth 2.0 or OpenID Connect [Security Requirement Object](/openapi/security#security-requirement-object) for an operation, the `{securitySchemeName}` field should contain a list of the scopes or roles required for the security scheme.

For example, the following Security Requirement Object indicates that the `read` and `write` scopes are required for the `oauth2` security scheme:

```yaml
paths:
  /drinks:
    get:
      operationId: listDrinks
      summary: Get a list of drinks
      # Operation requires read and write scopes
      security:
        - oauth2:
            - read
            - write
      # ...
```

### Disabling security requirements for specific operations

You can disable security for a specific operation by providing an empty array (`[]`) in the list of security requirements.

In this example, the `POST` operation in the `/auth` path does not require security, despite the global security requirement of an API key:

```yaml
security:
  - apiKey: []
paths:
  /auth:
    post:
      operationId: authenticate
      summary: Authenticate with the API
      security: [] # Disable security for this operation
      # ...
```

### Optional security

You can make security optional by providing an empty object (`{}`) in the list of security requirements.

In this example, the API may be accessed with or without an API key:

```yaml
security:
  - apiKey: []
  - {}
```

### Optional security for specific operations

Similarly, you can make security optional for a specific operation by providing an empty object (`{}`) in the list of security requirements.

This does not disable the security requirements defined at the document level, but makes them optional for this specific operation.

In this example, the `GET` operation in the `/drinks` path may be accessed with or without an API key, but if authenticated, the response will include additional information:

```yaml
paths:
  /drinks:
    get:
      operationId: listDrinks
      summary: Get a list of drinks. If authenticated, this will include stock levels and product codes, otherwise it will only include public information.
      security:
        - {} # Make security optional for this operation
      # ...
```

### Requiring multiple security schemes

If multiple schemes are required together, then the [Security Requirement Object](/openapi/security#security-requirement-object) should be defined with multiple security schemes.

In this example, both an API key **AND** basic auth are required to access the API:

```yaml
security: # both apiKey AND basic are required
  - apiKey: []
    basic: []
```

### Complex authorization scenarios

You can use this **AND**/**OR** logic, along with optional (`{}`) security, in any combination to express complex authorization scenarios.

In this example, the API may be accessed with an API key **AND** OAuth 2.0, **OR** with basic authentication:

```yaml
security: # apiKey AND oauth2 OR basic
  - apiKey: []
    oauth2:
      - read
      - write
  - basic: []
```