In an OpenAPI oauth2 security scheme, what do the flows object and its scopes declare?

## The shape of the object A scheme of `type: oauth2` has one required field, `flows`, whose members are the grant types the API accepts. Each member carries its endpoint URLs and its own `scopes` map. At least one flow must be present. ## The four flows and their required fields - **`authorizationCode`** — requires `authorizationUrl` and `tokenUrl`. The flow for applications acting on a user's behalf. - **`clientCredentials`** — requires `tokenUrl`. Machine-to-machine, no end user present. - **`password`** — requires `tokenUrl`. The client collects the user's credentials directly. - **`implicit`** — requires `authorizationUrl` only, since the token comes back from the authorization endpoint. All four accept an optional `refreshUrl`, and all four require a `scopes` map, which may be an empty object if the API defines no scopes. OpenAPI still defines `implicit` and `password` even though current OAuth security guidance discourages both; the document describes what an API accepts, so if the service still honours them, declaring them is the honest thing to do — and the presence of an `implicit` flow in a document is itself a useful review signal. Note that the flow **names in OpenAPI 3.x differ from Swagger 2.0**, which used `application` and `accessCode` for what are now `clientCredentials` and `authorizationCode`. Converted documents frequently carry the old names, which are invalid in 3.x. ## Scopes: declaration and reference The `scopes` map inside each flow is the authoritative list for that flow: keys are scope names exactly as the authorization server issues them, values are human-readable descriptions that documentation renderers display beside the checkboxes in an Authorize dialog. A security requirement may reference only names declared here — an operation asking for `read:pets` is valid because that key appears in the map; a typo is not caught by JSON-schema validation of the document but is caught by most linters and by any tool that resolves the reference. Because each flow has its own `scopes` map, a scope available under `authorizationCode` need not exist under `clientCredentials`. That is how you say a machine client can administer the catalogue but a user-delegated token cannot, or the reverse. ## openIdConnect as the alternative A scheme of `type: openIdConnect` with an `openIdConnectUrl` delegates all of this to the provider's discovery document instead of restating flows, endpoints and scopes inline. The advantage is that the document cannot drift from the provider's real configuration; the cost is that neither a reader nor an offline tool can tell what the API accepts without fetching that URL. Teams that want their spec to be self-contained — for air-gapped review, or for generators that do not fetch — keep the oauth2 form and accept the maintenance. ## Declaration is not enforcement — the point interviewers push on Nothing in the document verifies a token or checks a scope. Naming a scope on an operation does not cause any request to be rejected. Enforcement lives in the gateway, the framework's filter chain or the handler. The consequences of forgetting this are concrete: - A spec claiming an operation needs a write scope while the service checks nothing produces integrators who believe they are safe and an endpoint that is not. - A spec omitting a scope the service does enforce produces clients that request too little and receive a 403 they cannot diagnose from the documentation. - Scope names drifting from what the authorization server issues produces an Authorize dialog whose checkboxes mint tokens the API rejects. The mitigations are engineering, not syntax: generate the gateway's scope configuration from the same source as the document, or run contract tests that call each operation with a deliberately under-scoped token and assert the rejection. In a senior interview, naming that drift and one concrete way of catching it is the substance of the answer; reciting the four flow names is the preliminary. ## A review checklist - Only the flows the service really accepts are declared; an `implicit` flow is questioned rather than copied forward. - Every flow has the URLs its grant type requires, pointing at the real authorization server. - Scope names match what the authorization server issues, character for character. - Every scope referenced by an operation exists in the flow's `scopes` map. - There is a test, somewhere, that fails when the declared scope and the enforced scope diverge.