In an OpenAPI document, how does operation-level security interact with the root security block?

## Two places, one field The `security` field appears in exactly two positions in an OpenAPI 3.x document: at the **root**, where it sets the default for the whole API, and on an **Operation Object**, where it applies to that operation. It does **not** exist on the Path Item Object — so you cannot declare "everything under `/admin` needs the admin scheme" in one place. That absence surprises people who expect the inheritance model of parameters, which do have a path-item level. ## Override, not merge The rule is replacement. If the root requires `bearerAuth` and an operation declares `apiKeyAuth`, then that operation requires the API key **and not** the bearer token. The root requirement does not survive underneath. This trips people who reason by analogy with parameters, which merge. If an operation genuinely needs both, it must list both — and in that case the shape of the list matters, because two entries in one requirement object mean *and* while two objects in the array mean *or*. ## The empty array: opting out `security: []` on an operation removes any inherited requirement. It is the only way to say "this one is public" in a document with a root-level default, and it is what you write on: - the login or token endpoint, which by definition cannot require the credential it issues - a health or readiness probe - public metadata endpoints - callbacks the API itself receives from a third party under a different trust model Omitting `security` entirely on the operation is **not** the same thing: an absent field means "inherit the root default", while an empty array means "require nothing". That one-character difference between `security: []` and no `security` key at all is the most common defect in this area, and it fails in the dangerous direction only half the time — the other half it silently marks a protected endpoint as public in the documentation and in generated clients. ## The empty requirement object: making auth optional A related and distinct construct is an **empty Security Requirement Object** — `{}` — appearing as an element of the array. Because the elements of a `security` array are alternatives, and one of the alternatives is "no requirement at all", a list holding both `bearerAuth` and `{}` declares that a caller **may** authenticate but need not. That is the correct declaration for an endpoint whose response differs for authenticated callers — a feed that shows more items when you are logged in, say — as opposed to one that is flatly public. It can be written at the root too, making optional authentication the API-wide default, which is almost never what you want. ## Interaction with tooling Documentation renderers use this resolution to decide whether to show a lock icon on an operation; Swagger UI will not send the credential to an operation whose effective requirement is empty. Client generators decide per-operation whether to attach a credential interceptor. Lint rule sets commonly assert that the root declares `security` and that every operation-level `security: []` carries a description justifying it, because an unexplained opt-out is exactly what an attacker looks for in a published spec. ## Reviewing this in practice The practical discipline: declare the strictest common requirement at the root, keep operation-level `security` rare and always deliberate, and treat every `security: []` as something that must be justified in review. Then check the resolved view — most tools can show the effective requirement per operation — rather than reading the YAML and reasoning about inheritance in your head. And remember throughout that this resolution describes what clients should send; it does not configure any gateway, so an operation documented as public and an operation actually served anonymously are two independent facts that must be kept in agreement by testing, not by the document alone.