OpenAPI Security Schemes Reference
OpenAPI security schemes describe how callers present credentials. They improve documentation and generated clients but do not enforce access by themselves.
Scheme types
| Type | Use |
|---|---|
| apiKey | A named key in a header, query parameter, or cookie. |
| http | An HTTP authentication scheme such as Basic or Bearer. |
| oauth2 | OAuth 2.0 flows, authorization URLs, token URLs, and scopes. |
| openIdConnect | An OpenID Connect discovery URL. |
| mutualTLS | Mutual TLS authentication in OpenAPI versions that support it. |
API keys
An apiKey scheme declares its field name and location. Prefer a request header when possible because query values are more likely to enter access logs, browser histories, analytics, and referrers. OpenAPI cannot define the key's secret lifecycle, hashing, rotation, tenant scope, or permissions; document and enforce those behaviors in the real service.
HTTP Basic and Bearer
For HTTP Basic, use type http with the basic scheme and require HTTPS. For Bearer, declare the bearer scheme and optionally a descriptive bearer format, but do not assume that every bearer token is a JWT. The format hint does not replace issuer, signature, audience, expiry, token-type, scope, and permission validation.
OAuth 2.0 flows
An OAuth 2.0 scheme can document authorization code, client credentials, implicit, and password flows supported by the OpenAPI version. Prefer authorization code with PKCE for interactive public clients and client credentials for service identity where appropriate. Legacy implicit and password flows should not be introduced into new designs. Scopes in the scheme describe requested delegated permissions, not resource ownership.
OpenID Connect
An OpenID Connect scheme points to provider discovery metadata. Discovery helps clients locate endpoints and capabilities, while runtime validation still needs an exact issuer and trusted configuration. ID tokens authenticate a user to a client and are not automatically access tokens for an API. Document the protected resource's required token and claims.
Security requirements
A top-level security array applies default requirements to operations. An operation can override that array, and an empty array can make an operation anonymous under the document semantics. Separate requirement objects represent alternatives: API key or OAuth. Multiple scheme names inside one requirement object are combined: both are required. For OAuth or OpenID Connect, the value lists required scopes; other schemes normally use an empty array.
Authorization remains separate
A valid credential proves only what its scheme and issuer assert. The application must enforce roles, scopes, tenant boundaries, resource ownership, state transitions, and rate limits. Do not publish real secrets in examples or server variables. Generated “Authorize” dialogs are developer conveniences, not proof that an endpoint is protected.
Verification
Lint unresolved names, missing flows, incorrect URLs, accidental anonymous overrides, and requirements unsupported by the gateway. Test one accepted and rejected request for every operation policy. Inspect the rendered contract with the OpenAPI Viewer.
Frequently Asked Questions
Does the scheme enforce auth?
No. Runtime infrastructure must enforce it.
How are alternatives represented?
Separate security objects are alternatives; names in one object are combined.
Should keys use query parameters?
Prefer headers when possible to reduce leakage.