OpenAPI 3.x SecurityRequirements with least-privilege scopes and token expiry documentation

To document least-privilege authentication in OpenAPI 3.x, you should define all possible scopes within the components/securitySchemes object and then reference only the minimum required scopes within the security requirement of each individual operation.

Implementing Least-Privilege Scope Mapping

The specification allows you to override global security settings at the operation level. To signal least-privilege intent, avoid defining a broad global security requirement. Instead, explicitly list the narrowest possible scopes for every endpoint.

components:
  securitySchemes:
    OAuth2: # The central definition
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.example.com/token
          scopes:
            read:read: "Read-only access to resources"
            write:admin: "Administrative write access"

paths:
  /resource:
    get:
      summary: Get resource
      security:
        - OAuth2: ["read:read"] # Minimal scope for this operation
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized - Token expired or missing
        '403':
          description: Forbidden - Insufficient scope (e.g., requires read:read)

Handling Token Expiry and Refresh Flows

Because OpenAPI 3.x does not provide a normative field for token TTL (Time-to-Live) or refresh logic, these must be documented using descriptive text or vendor extensions. Since these details are usually consistent across the entire API, the description field of the security scheme is the most consistent location.

Recommended Documentation Patterns

• Scheme Description: Use the description field in components/securitySchemes to define the token lifetime (e.g., "Tokens expire after 3600 seconds") and the refresh mechanism.
• Response Descriptions: Use the responses object for 401 and 403 to distinguish between authentication failure (expired/invalid token) and authorization failure (valid token, but missing the required scope).
• Custom Extensions: For machine-readable expiry data, use a vendor extension such as x-token-ttl: 3600.

Verification Steps

To ensure your documentation remains consistent with your implementation:

1. Cross-Reference: Verify that every scope string used in an operation's security block is explicitly declared in the components/securitySchemes scopes list.
2. Linting: Use a linter like Spectral to enforce a rule that every operation must have an explicit security block, preventing accidental fallback to overly-permissive global defaults.
3. Response Audit: Ensure that every operation referencing a security scheme also defines both 401 and 403 responses to guide the client on how to handle expiry vs. permission gaps.

Diagnostic Detail Required: Are you using a standardized identity provider (like Okta or Auth0) or a custom implementation? This determines whether you should reference external RFCs (like RFC 6749) in your descriptions or provide detailed custom refresh flow steps.