A security scheme defines how an API consumer authenticates or gains authorization. In OpenAPI, schemes live under components.securitySchemes, where each named scheme can organize scopes for access control. section 12.9.1
Define a scheme with a suitable type and flow, then provide required flow URLs such as authorizationUrl. Add scopes as named keys with descriptions; quote names containing colons in YAML. section 12.9.1
Applying scopes to an operation
A security list on POST /beneficiaries can require beneficiary:create or beneficiary:all. The consumer must satisfy one security-list element, using a scope defined by its selected scheme. section 12.9.2
Choose and evolve schemes with the consumer and change impact in mind:
- Use multiple schemes when scopes need separate groups, such as fine-grained and coarse-grained permissions or consumer-specific permissions. section 12.9.1
- For webhooks, declare OpenAPI-handled security such as mutual TLS under components.securitySchemes and reference it from the webhook operation. section 14.6.9
- Treat scheme replacement and scope changes as compatibility work: offer old and new modes temporarily when possible, and review added permissions for breaches. section 15.3
- Reference schemes by name rather than $ref when building reusable OpenAPI component libraries. section 17.6.1
Figure 12.10 Define scopes in security schemes under components.securitySchemes. You can define multiple security schemes to organize scopes.
Use the figure to inspect how schemes and scopes are organized beneath components.securitySchemes. section 12.9.1
Figure 12.11 The security list contains the security schemes and scopes a consumer needs to use to access an operation.
Use the figure to inspect how an operation declares its acceptable security schemes and scopes. section 12.9.2
