# Security Schemes and Requirements — OpenAPI / Swagger

Source: https://www.skillbyai.com/en/openapi/sec-schemes

> Describe API keys, HTTP auth, bearer tokens and mutual TLS, and apply them to operations.

## Documenting how clients authenticate

Authentication methods are declared once in **`components/securitySchemes`** and then applied with **security requirements**. Scheme types: **`apiKey`** (a key in a header, query parameter or cookie, with `name` and `in`); **`http`** with `scheme: basic` or `scheme: bearer` (optionally `bearerFormat: JWT`); **`oauth2`** with one or more **flows**; **`openIdConnect`** with a discovery URL; and **`mutualTLS`** (3.1) for client certificates. The top-level **`security`** field sets a default for all operations, and each operation can override it: `security: []` makes an operation public (such as a health check or login), and a list of alternatives means **any one** suffices, while several schemes in the same requirement object must **all** be satisfied. Documentation tools use these declarations to render "Authorize" buttons, and generators wire authentication into SDKs. OpenAPI only **describes** security; it does not enforce it. Your gateway or application must still validate credentials, and should never place secrets such as API keys in query strings, where they end up in logs.

## Security declared once, applied everywhere

Schemes are defined in components; operations reference them as requirements.

![A shield icon at the top connected by thin lines to a column of operation bars, with one bar connected to an open padlock instead.](assets/figures/openapi/section-4-map.svg) — Figure 4.1 — Global security with a public operation override.

## Bearer tokens by default, API keys for partners, a public health check

Alternatives are listed separately; an empty array means no authentication.

```yaml
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    partnerKey:
      type: apiKey
      in: header
      name: X-Partner-Key

security:
  - bearerAuth: []                     # default for every operation

paths:
  /health:
    get:
      operationId: health
      security: []                     # public
      responses: { '200': { description: OK } }
  /partner/orders:
    get:
      operationId: listPartnerOrders
      security:
        - partnerKey: []               # either a partner key ...
        - bearerAuth: []               # ... or a user token
      responses: { '200': { description: Orders } }
```

## Document 401 and 403 too

Declaring a security scheme is not enough for clients. Document the 401 (missing or invalid credentials) and 403 (authenticated but not allowed) responses with their error bodies, so integrators can handle them.

**Quiz:** What does `security: []` on an operation mean?

- [ ] The operation is forbidden
- [ ] All security schemes are required
- [x] The operation requires no authentication, overriding the global default
- [ ] The document is invalid

*Answer:* The operation requires no authentication, overriding the global default. An empty security array removes authentication requirements for that operation.