Authentication & authorization
OpenAPI 2.0 defines four auth flavours; the runtime covers all four
plus the orthogonal Authorizer step. The pages below walk one
concrete scenario each — the first three cover the simplest cases,
the rest progressively layer on scopes, composition and custom
business rules.
When to use which
| Situation | Start with |
|---|---|
| Single static API key in a header or query param | api-key |
| Username:password against a local store | basic |
| OAuth2 / OIDC bearer tokens with scope checks | bearer-jwt |
| You actually need the OAuth2 access-code dance with Google | oauth2-access-code |
| Multiple schemes per operation (AND / OR composition) | composed |
| RBAC / per-route business rules over the principal | custom-authorizer |
| Client side — attaching credentials to outgoing requests | client-side |
For the conceptual model (interfaces, lifecycle, where each stage fires), see server / security and core / interfaces.
- Simplest server-side auth — a single API key carried in a header (or query parameter), validated against a static map.
- RFC 7617 Basic auth with realm and a WWW-Authenticate challenge on failure.
- OAuth2-style Bearer tokens carrying a JWT — verified locally, scope-checked against the operation’s required scopes.
- Multiple security schemes per operation — AND inside an entry, OR between entries — with a single principal type.
- Full OAuth2 access-code handshake against Google — login redirect, callback handler, token exchange and protected operations.
- Pluggable Authorizer that gates the principal for the matched operation — a worked role-based access control example, orthogonal to whichever Authenticator was used.
- Attaching auth information to outgoing requests — Basic, API key, Bearer, composed writers, and a custom HMAC signer.