How can I use OpenAPI overlays to create partner-specific API subsets?

How can I use OpenAPI overlays to create partner-specific API subsets? #

When onboarding integration partners, it’s common to grant access to only a handful of endpoints relevant to the specific integration — a payments partner might only need order and refund endpoints, while a logistics partner needs shipping and tracking endpoints. Hand-crafting a separate OpenAPI document per partner duplicates effort and drifts out of sync as the main API evolves. The OpenAPI Overlay Specification makes it possible to define each partner’s subset as a small, explicit overlay rather than a forked document.

The Allow-List Approach: Remove Everything Not Needed #

Because overlays are best suited to targeted removals and updates rather than expressing “keep only these,” the most reliable pattern is to explicitly remove everything the partner should not see:

overlay: 1.0.0
info:
  title: Payments Partner Subset Overlay
  version: 1.0.0
actions:
  - target: $.paths['/shipping']
    remove: true
  - target: $.paths['/tracking/{id}']
    remove: true
  - target: $.paths['/inventory']
    remove: true

Generating the Removal List Programmatically #

For APIs with many endpoints, maintaining an explicit “keep list” per partner and generating the corresponding removal overlay automatically scales much better than writing dozens of remove actions by hand:

const keepForPaymentsPartner = ['/orders', '/orders/{id}', '/refunds'];
const actions = [];

for (const path of Object.keys(spec.paths)) {
  if (!keepForPaymentsPartner.includes(path)) {
    actions.push({ target: `$.paths['${path}']`, remove: true });
  }
}

This flips the mental model from “remember what to remove” to “declare what to keep,” while still producing a standard overlay file underneath.

Scoping Down Schemas Alongside Paths #

Removing paths can leave behind schema components the partner shouldn’t have visibility into either (even just as documentation). Include schema removals in the same overlay:

  - target: $.components.schemas.ShippingLabel
    remove: true
  - target: $.components.schemas.WarehouseLocation
    remove: true

Adding Partner-Specific Security Requirements #

Partner subsets often pair naturally with a dedicated security scheme scoped to that partner’s credentials:

  - target: $.paths['/orders'].get
    update:
      security:
        - partnerApiKey: []

Structuring Overlays per Partner #

overlays/
  partner.overlay.payments-co.yaml
  partner.overlay.logistics-co.yaml

Building and Delivering Partner Specs #

redocly join openapi.yaml --overlay overlays/partner.overlay.payments-co.yaml -o dist/openapi.payments-co.yaml

The resulting document can be delivered directly to the partner (as a downloadable spec) or used to generate a partner-specific documentation portal, all without exposing capabilities outside the scope of that integration agreement.

See What is the OpenAPI Overlay Specification? and How can I use OpenAPI overlays to generate audience-specific API documentation? for the broader multi-audience pattern this technique belongs to.

Last updated on July 16, 2026.