How can I use OpenAPI overlays to add security requirements to specific operations?

How can I use OpenAPI overlays to add security requirements to specific operations? #

Security requirements sometimes need to change independently of the operation’s business logic — an endpoint might move from optional authentication to mandatory OAuth scopes as it matures, or a partner-specific document might require an additional API key on top of the standard bearer token. The OpenAPI Overlay Specification lets you apply these changes as an overlay rather than editing the operation definition directly.

Adding a Security Requirement to One Operation #

overlay: 1.0.0
info:
  title: Enforce OAuth Scopes Overlay
  version: 1.0.0
actions:
  - target: $.paths['/orders'].post
    update:
      security:
        - oauth2:
            - "orders:write"

This assumes the oauth2 scheme and its scopes are already declared in components.securitySchemes in the base document; the overlay only attaches the requirement to the operation.

Layering an Additional API Key for Partner Integrations #

  - target: $.paths['/reports'].get
    update:
      security:
        - oauth2:
            - "reports:read"
          partnerApiKey: []

Declaring the Scheme Itself via Overlay #

If the security scheme itself needs to be introduced only for a specific audience document (for example, a partner-only API key scheme that shouldn’t appear in the public spec), add it to components.securitySchemes through the overlay as well:

  - target: $.components.securitySchemes
    update:
      partnerApiKey:
        type: apiKey
        in: header
        name: X-Partner-Key

Making an Operation Public (Removing Security) #

Sometimes an overlay needs to go the other direction — for a sandbox or demo environment, security might be relaxed entirely by setting an empty security requirement:

  - target: $.paths['/public/status'].get
    update:
      security: []

An empty array explicitly overrides any global security requirement, marking the operation as unauthenticated for that specific overlay output.

Progressive Security Rollouts #

When rolling out a new authentication requirement gradually, maintain a “future state” overlay describing the eventual security posture, and merge it into a staging build well ahead of the production cutover date. This lets client teams validate against the new requirements before the change goes live everywhere.

redocly join openapi.yaml --overlay security/oauth-rollout-2026-q4.yaml -o dist/openapi.staging.yaml

Validating Security Overlays #

Security-related overlay changes deserve extra scrutiny in code review since a mistake could either lock out legitimate consumers or unintentionally expose an operation. Pair any security overlay change with a lint rule (for example, a custom Spectral rule) that fails the build if any operation ends up with no security requirement unless explicitly allow-listed.

See What is the OpenAPI Overlay Specification? for the general model, and How can I use OpenAPI overlays to manage multi-tenant API documentation? for a related use case involving tenant-specific access rules.

Last updated on July 16, 2026.