Declare each auth method under components.securitySchemes with a type of http, apiKey, oauth2, openIdConnect or mutualTLS, then reference it in a top level or per operation security entry. A scanner reads those entries to know what credential to send. Without them it only sees the login wall.
The five scheme types
The OpenAPI Specification lists the valid type values as apiKey, http, mutualTLS, oauth2 and openIdConnect.
| Type | Required fields | Typical use |
|---|---|---|
| http with scheme bearer | scheme, optional bearerFormat | Token in the Authorization header |
| apiKey | name, in (query, header or cookie) | Static key sent by the client |
| oauth2 | flows | Authorization code, client credentials and others |
| openIdConnect | discovery URL | OIDC based login |
| mutualTLS | none beyond type | Client certificates |
For bearer, the spec describes bearerFormat as "a hint to the client to identify how the bearer token is formatted", with JWT as its example. It is documentation, not validation.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []
How top level and operation level interact
A root level security field declares which mechanisms can apply across the API, and operations can override it. An operation's security replaces the top level one. Details on the override edge cases are in the empty security array post.
What the frameworks generate
| Framework | What you do |
|---|---|
| FastAPI | Using OAuth2PasswordBearer puts an OAuth2 scheme in the description, and tokenUrl is recorded there |
| Spring with springdoc | Add configuration or annotations that describe your scheme |
| NestJS | Add auth options on the document builder and decorators on controllers |
| Rails | No generator in the base framework, so write or maintain the file yourself |
The FastAPI behavior is documented: tokenUrl declares where clients get a token and that information goes into OpenAPI and the interactive docs. For Spring, NestJS and Rails, check your library version's documentation, since the specifics vary.
Steps
- Pick one scheme per real auth method. Do not declare schemes your API does not accept.
- Put the common one in the root security field.
- For public routes, override with an empty list on that operation only.
- Export the description and read it as a scanner would. Does every protected operation list a scheme?
- Give the scanner a test token for each role, or the details to obtain one.
- Run one scan and check that protected routes returned 200 with the credential and 401 without it.
Mistakes to avoid
- Declaring a scheme but never referencing it in security. It appears in components and does nothing.
- Declaring bearer when the app really uses a cookie.
- Letting the generator guess. A generated description reflects code annotations, so unannotated routes can show no security at all.
Try it yourself
Click through it at your own pace, or open it full screen. Look for where the credential is supplied to the scan.
Safeguard's SBOM and dependency scanning covers the libraries that generate these descriptions, and a free scan is available.
Quick check
Does bearerFormat enforce JWT?
No. It is a hint to clients about token format.
Where do I put the scheme name for a route?
In a security entry, at the root or on the operation, that names a scheme defined under securitySchemes.
Sources
Last reviewed: 19 October 2026.
