OpenAPI 3.x security requirements and scope-based permission modeling

Implementing a least-privilege security model in OpenAPI 3.x requires a decision on how to represent fine-grained permissions within the security array. While the specification allows for the definition of securitySchemes under components, there is ambiguity in how to best map complex server-side authorization policies to the documentation.

The current challenge involves choosing between three distinct modeling patterns:

• Defining granular permissions as individual OAuth2 scopes.
• Using multiple alternative security requirements to represent AND/OR logic for access.
• Abstracting the permissions entirely and relying on server-side policy enforcement.

Because Swagger UI and generated clients interpret these requirements differently—particularly regarding how scopes are requested during the authorization flow—inconsistent modeling can lead to confusion between HTTP 401 (Unauthorized) and HTTP 403 (Forbidden) responses.

Technical Questions

• What is the recommended pattern for modeling fine-grained permissions to ensure Swagger UI requests the minimum necessary scopes?
• How should the security array be structured to clearly distinguish between mandatory authentication and optional, scope-based authorization?