How can I use OpenAPI overlays to manage multi-tenant API documentation?

How can I use OpenAPI overlays to manage multi-tenant API documentation? #

In a multi-tenant SaaS platform, not every tenant has access to the same set of API capabilities. Enterprise-tier tenants might have access to bulk export endpoints and advanced webhooks, while starter-tier tenants see a smaller surface area. Maintaining a separate OpenAPI document by hand for each tier quickly becomes unsustainable as plans and feature flags change. The OpenAPI Overlay Specification lets you express each tier’s documentation as a small diff against a single, feature-complete base document.

Tagging Tier-Gated Operations in the Base Document #

paths:
  /exports/bulk:
    post:
      x-plan-tier: "enterprise"
      summary: Trigger a bulk data export
  /webhooks:
    get:
      x-plan-tier: "pro"
      summary: List configured webhooks
  /orders:
    get:
      x-plan-tier: "starter"
      summary: List orders

Overlay for the Starter Tier #

The starter-tier overlay removes anything above its own tier:

overlay: 1.0.0
info:
  title: Starter Tier Documentation Overlay
  version: 1.0.0
actions:
  - target: $.paths['/exports/bulk']
    remove: true
  - target: $.paths['/webhooks']
    remove: true

Overlay for the Pro Tier #

overlay: 1.0.0
info:
  title: Pro Tier Documentation Overlay
  version: 1.0.0
actions:
  - target: $.paths['/exports/bulk']
    remove: true

Overlay for the Enterprise Tier #

The enterprise tier typically needs no removals at all — its overlay might instead add extra content, like dedicated support contact details:

overlay: 1.0.0
info:
  title: Enterprise Tier Documentation Overlay
  version: 1.0.0
actions:
  - target: $.info
    update:
      description: "Full API access including bulk exports and webhook management, available on the Enterprise plan."

Generating Tier-Specific Overlays From Plan Configuration #

If your billing or entitlements system already defines which x-plan-tier values map to which plan, a script can generate the “remove everything above my tier” overlay automatically rather than hand-maintaining it:

const tierOrder = ['starter', 'pro', 'enterprise'];
const myTierIndex = tierOrder.indexOf(targetTier);

for (const [path, methods] of Object.entries(spec.paths)) {
  for (const [method, operation] of Object.entries(methods)) {
    const opTier = operation['x-plan-tier'] || 'starter';
    if (tierOrder.indexOf(opTier) > myTierIndex) {
      actions.push({ target: `$.paths['${path}'].${method}`, remove: true });
    }
  }
}

Building Per-Tier Documentation #

for tier in starter pro enterprise; do
  redocly join openapi.yaml --overlay "overlays/tier.overlay.$tier.yaml" -o "dist/openapi.$tier.yaml"
done

Each tenant, when visiting the documentation portal, can be routed to the generated document matching their current plan, ensuring they never see endpoints they can’t actually call.

Keeping Entitlements and Documentation in Sync #

Because the tier overlay logic can be generated straight from the same entitlements configuration that drives runtime authorization, documentation and actual API access stay aligned automatically as plans change, rather than requiring a manual update in two separate places.

See What is the OpenAPI Overlay Specification? and How can I use OpenAPI overlays to create partner-specific API subsets? for a related audience-scoping technique.

Last updated on July 16, 2026.