# Security in OpenAPI
Source: https://speakeasy.com/openapi/security

import { Table } from "@/mdx/components";



When designing an API, it's important to consider the security requirements for accessing the API. The OpenAPI Specification 3.1 provides a way to define security requirements at both the document and operation levels.

Firstly, "security" is a general term that covers multiple authentication and authorization systems commonly used to ensure API operations are used only by the intended actors.

OpenAPI divides security into two parts:

- **Security schemes**, which are defined as reusable components.
- **Security requirements**, which invoke the reusable security schemes either across the whole API or within specific operations.

The following simple example of an API key demonstrates the basic security structure defined in the OpenAPI Specification:

```yaml
security:
  - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: Speakeasy-API-Key
      in: header
```

## Supported security schemes

Before you can reference a [security scheme](/openapi/security/security-schemes) as a requirement in the `security` section, it must be defined in the [Components Object](/openapi/components) under `securitySchemes`.

The OpenAPI Specification 3.1 supports the following security schemes:

- [API Key](/openapi/security/security-schemes/security-api-key)
- [HTTP Authorization](/openapi/security/security-schemes/security-http) (such as Basic, Digest, and Bearer)
- [OAuth 2.0](/openapi/security/security-schemes/security-oauth2)
- [OpenID Connect](/openapi/security/security-schemes/security-openid)
- [Mutual TLS](/openapi/security/security-schemes/security-mutualtls)

Once you've defined an API's security schemes, you can reference them in the `security` section of the OpenAPI document or at the operation level.

## The Security Requirement Object

A Security Requirement Object defines a map of security scheme names with an array of [scopes or roles](#security-requirement-scopes-or-roles) that are required to access an API (or specific operation).

The names **must** match the names of the [Security Scheme Objects](/openapi/security/security-schemes) defined in the [Components Object](/openapi/components) under the `securitySchemes` field.

<Table
  data={[
    {
      field: "{securitySchemeName}",
      type: "List<string>",
      required: "",
      description:
        "A list of [scopes or roles](#security-requirement-scopes-or-roles) required for the security scheme. If the security scheme type is `oauth2` or `openIdConnect`.",
    },
  ]}
  columns={[
    { key: "field", header: "Field" },
    { key: "type", header: "Type" },
    { key: "required", header: "Required" },
    { key: "description", header: "Description" },
  ]}
/>

## Global authentication vs endpoint authentication

Security can be applied at two levels in OpenAPI:

- **Global security:** The security specified is available for all operations.
- **Per-operation security:** The security is only applied to the operation, overriding any global-level security.

The following example demonstrates how to describe security at both levels:

```yaml
security:
  - apiKey: [] # Global security requirement
paths:
  /drinks:
    get:
      operationId: listDrinks
      summary: Get a list of drinks
    post:
      operationId: createDrink
      summary: Create a new drink
      security:
        - apiKey: [] # Per operation security requirement
```

The [`security`](https://spec.openapis.org/oas/v3.1.0#security-requirement-object) and [`securitySchemes`](https://spec.openapis.org/oas/v3.1.0#security-scheme-object/security-schemes) sections (representing the Security Object and Security Scheme Object, respectively) are most important in this example.

## Working with security requirements

Depending on the API, security requirements can be simple or complex. The following examples illustrate how to work with security requirements in OpenAPI.

### Simple API security

All the operations in an API may require an API key for access. You can define this requirement at the document level using the `security` section.

```yaml
security:
  - apiKey: []

paths:
  /drinks:
    get:
      operationId: listDrinks
      summary: Get a list of drinks
    post:
      operationId: createDrink
      summary: Create a new drink

components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: Speakeasy-API-Key
      in: header
```

### Public reads, protected writes

A simple API might have some publicly accessible endpoints, but require an API key for others. You can use the `security` section to define the security requirements either for the entire API or for specific operations.

```yaml
security: [] # No global security requirements
paths:
  /drinks:
    get:
      operationId: listDrinks
      summary: Get a list of drinks
    post:
      operationId: createDrink
      summary: Create a new drink
      security:
        - apiKey: [] # This operation requires an API key
```

### Multiple security schemes

A more complex API may have different security requirements for different operations, or even allow multiple security schemes to be used interchangeably.

In the following example, the API can be accessed with either an API key or OAuth 2.0. OAuth 2.0 allows for more granular access control using the concept of scopes, which can be defined in the `securitySchemes` section and referenced in the `security` section for specific operations.

```yaml