OpenAPI 3.x SecurityRequirements with least-privilege scopes and token expiry documentation
18.5K reputation · 07 May 2020, 04:57 UTC
Goal is to document least-privilege authentication using components.securitySchemes and per-operation security requirements in OpenAPI 3.x, with explicit permission boundaries per endpoint.
OpenAPI describes mechanisms such as OAuth2, HTTP bearer and API keys and allows minimal scopes to be listed per operation, but the specification is documentation only. It does not model token lifetime, refresh token flow details, or a normative way to document expired credential handling. Scope names are opaque strings with no defined semantics, and enforcement of scope boundaries is implementation specific.
With that constraint, what is a consistent way to document expected 401 Unauthorized and 403 Forbidden responses for expired credentials and insufficient scope in the same document? Should security requirements be limited to minimal scopes per operation to signal least-privilege intent, and how should refresh flow expectations be described without a standard field for token expiry?