Security Schemes

## Where schemes live Authentication in an OpenAPI document is described in two halves. The first half — this question — is the **definition**: a map at `components.securitySchemes` from an arbitrary name you choose to a Security Scheme Object. The second half is the **application**: `security` lists at the document root or on an operation that name those schemes. A scheme that is defined but never applied protects nothing; a `security` entry naming a scheme that does not exist in `components.securitySchemes` is an invalid document. The key you pick (`bearerAuth`, `apiKeyAuth`, `myOauth`) is just an identifier. It has no meaning to a client — it is not a header name, not a scheme name, not a scope — and it exists solely so `security` can refer to the definition. Renderers do surface it, so pick something readable. ## The type values **`apiKey`** — a value carried in a named field. Requires `name` (the field's name) and `in`, which is `query`, `header` or `cookie`. This is how you describe `X-API-Key: abc123` or `?api_key=abc123`. **`http`** — authentication using the HTTP `Authorization` header's own framework. Requires `scheme`, whose value is an HTTP authentication scheme name from the IANA registry defined alongside RFC 7235 — `basic`, `bearer`, `digest` and others. For `bearer`, an optional `bearerFormat` string hints at the token format (commonly the literal `JWT`). You do **not** describe the `Authorization` header as a header parameter; a header parameter with that name is explicitly ignored by the specification because this is where it belongs. **`oauth2`** — requires a `flows` object whose members are `implicit`, `password`, `clientCredentials` and `authorizationCode`. Each declared flow supplies the URLs it needs (`authorizationUrl`, `tokenUrl`, optional `refreshUrl`) and a required `scopes` map of scope name to human description. The `scopes` map is the registry of scope names the document may then reference. **`openIdConnect`** — requires only `openIdConnectUrl`, a URL to the OpenID Connect discovery document. The scheme delegates the details to that document rather than restating flows and endpoints inline. **`mutualTLS`** — added in OpenAPI **3.1**. It declares that the API authenticates the client by its TLS certificate, and it carries no additional fields. It does not exist in 3.0 documents. All five share the optional `description` field, which is CommonMark and is what documentation renderers show next to the Authorize control. ## What tooling does with a scheme Documentation renderers use the definitions to build their authorization UI — Swagger UI's **Authorize** dialog is driven entirely by `securitySchemes` plus the `security` lists. Client generators use them to add a credential parameter or an interceptor to the generated SDK. Server-stub generators may scaffold a security filter hook. Linters check that every applied name is defined and, in many rule sets, that at least one scheme is applied. ## What a scheme does not do A Security Scheme Object is a **declaration**, not an enforcement mechanism. Nothing about writing `type: http, scheme: bearer` causes any token to be verified; the gateway, framework or filter chain does that, and the document is only a description of what the client is expected to send. Drift between the two — a spec that says an operation is protected while the service happily serves it anonymously, or the reverse — is invisible to validators and is a real production hazard. ## Frequent mistakes The most common by far is describing bearer authentication as `type: apiKey, in: header, name: Authorization`. It renders roughly, and generated clients then require the caller to type the word `Bearer` themselves; the correct declaration is `type: http, scheme: bearer`. The habit comes from **Swagger 2.0**, which had no `http` type at all — it offered `basic`, `apiKey` and `oauth2` under a top-level `securityDefinitions` key. A second mistake is defining schemes and never applying them, which leaves generated clients with no way to send credentials at all.