Most teams that need to expose an API to partners reach for the same fix: stand up a second documentation site, gate it behind a login, and maintain it in parallel with the public docs. That reflex creates two sources of truth that drift apart, doubles the maintenance burden, and forces the same endpoint to be documented twice. The better approach is to serve public, partner, and internal audiences from one API definition and gate visibility with audience filtering and role-based access control. This guide walks through how to do that, and the single decision that determines whether partner documentation stays maintainable: keep one source of truth and control who sees what, rather than forking the portal.
TLDR:
- A separate partner portal duplicates content, splits the source of truth, and drifts out of sync with the public docs within a release or two.
- Audience filtering (via the
x-fern-audiencesextension) tags endpoints, schemas, and even individual properties, so one spec renders different views for public, partner, and internal developers. - Role-based access control gates who can see partner content, enforced at the page, section, API reference, and MDX-block level.
- Authentication ties visibility to identity through JWT, OAuth, SSO, or shared passwords, and the same access model extends to search and AI answers.
- Fern serves partner-only API documentation from a single source, applying audience filtering and RBAC without maintaining a second site.
Why a second partner portal is the wrong default
The instinct to build a separate portal is understandable. Partner endpoints often carry different rate limits, authentication schemes, and terms than the public API, and keeping them on their own site feels like the cleanest way to control access. In practice, the separation is where the problems start.
A second portal means the same base endpoints get documented in two places. When the API changes, both sites need updating, and the partner docs are almost always the ones that lag. Drift between an API's real behavior and its documentation is the failure mode that erodes developer trust fastest, and a parallel portal manufactures that drift by design. It also fragments discovery: partners who also use public endpoints have to bounce between two sites, and internal search covers neither completely.
The cost compounds with every audience. Add a beta program or a second partner tier and the "one extra site" becomes three or four, each with its own deploy pipeline, its own theme, and its own opportunity to fall behind. The maintenance burden scales with the number of portals, not the size of the API.
The alternative is to treat access level as an attribute of the content, not a property of the site. A single API definition can carry the metadata that says which endpoints belong to which audience, and the documentation platform can render the right subset for each reader after they authenticate. That is the model the rest of this guide builds.
What partner-only API documentation actually requires
Before choosing tooling, it helps to separate the two distinct jobs that "partner-only docs" bundle together:
- Filtering decides what content exists in a given view. A partner should see partner endpoints and shared public endpoints, but never the internal admin API. This is a content-shaping problem.
- Access control decides who is allowed into a gated view at all. A reader proves who they are, and the system maps that identity to a set of permissions. This is an authentication and authorization problem.
Both are required. Filtering without access control leaks internal endpoints to anyone who guesses the URL. Access control without filtering forces you back into separate sites, because a single undifferentiated doc set can only be all-or-nothing behind the login. A platform that does this well handles both from the same source specification, which is what lets one portal serve every audience.
Step 1: tag endpoints by audience in the spec
Audience filtering starts in the API definition itself. In an OpenAPI spec, the x-fern-audiences extension tags each endpoint, schema, or property with one or more audience identifiers such as public, partner, or internal. The documentation platform then filters the rendered reference to show only the endpoints tagged for the audience viewing it.
Because the tags live on the spec, the same source generates every view. A partner-facing site filters to partner and public; the internal site includes everything. There is no second file to keep in sync, and a new endpoint inherits the correct visibility the moment its audience tag is set.
Two capabilities matter for real partner programs:
- Property-level filtering. Partner and public developers often need the same endpoint but different fields on it. Audience tags applied at the property level hide individual object properties, with example payloads scrubbed automatically so a filtered field never leaks through a code snippet.
- Inverse tagging. Some platforms are internal-first, where most endpoints are private and only a subset is exposed externally. Audience filtering supports defining a default visibility and tagging only the exceptions, so teams are not forced to annotate every endpoint just to hide the majority.
Tagging is what lets a single spec drive a public reference, a partner reference, and an internal reference without duplicating a line of it.
Step 2: gate partner content with role-based access control
Filtering shapes the view; role-based access control decides who is allowed to load it. RBAC maps an authenticated reader's role, team, or pricing tier to the specific pages and sections they can see. A partner role unlocks the partner endpoints; an unauthenticated visitor sees only the public content.
Granularity is what makes single-portal partner docs viable. Access control that stops at the project or workspace level forces a separate documentation instance per audience, which is the second portal by another name. Restricting at the page, section, API-reference, and MDX-block level lets partner-only guidance live on the same page as public content, revealed only to readers whose role permits it. A single quickstart page can show public setup steps to everyone and a partner-only authentication section to signed-in partners.
Role assignments can also update dynamically. When a partner's tier changes in your own system, the documentation they see on their next login reflects it, without anyone manually re-gating pages. One important operational detail: RBAC defaults to requiring authentication for all content unless a page is explicitly marked as viewable by everyone, so public pages are an opt-in rather than an accident. That default-deny posture is the safe one for partner programs, but it means the public surface has to be declared deliberately.
Step 3: connect access control to partner identity
RBAC needs to know who the reader is, which is the job of authentication. Partner programs rarely fit one mold, so it helps that there is more than one way to authenticate readers:
- JWT connects docs to an existing partner portal or dashboard. A partner already logged into your platform is handed a signed token, and the docs read their identity and permissions from it without a second login. Tokens can carry custom claims, so partner tier or organization maps straight onto documentation roles.
- OAuth and SSO integrate with enterprise identity providers such as Okta, using SAML or OIDC. This suits partners whose own security teams require federated login and central deprovisioning.
- Password protection is the lightweight option. Multiple passwords can map to different roles, giving partners, beta testers, and internal reviewers tiered access without standing up an identity provider. It is the fastest way to gate a partner preview.
The right choice depends on the partner relationship. A self-service partner program built on an existing customer portal usually wants JWT; an enterprise integration with a named partner usually wants SSO. All of them feed the same RBAC layer, so the filtering and gating logic does not change with the login method.
Step 4: let partners test without leaving the docs
Reading partner endpoints is only half the job. Partners also need to try them, and forcing them to copy credentials into a separate tool is where onboarding stalls. Documentation that injects a partner's API key into an interactive explorer lets them authenticate and run live calls directly from the reference. The key is populated from their JWT or OAuth session, so there is no copy-paste step and no shared secret in plain text.
This is what makes self-service partner onboarding realistic. A partner can discover the endpoints their role permits, authenticate against a sandbox, and make a first successful call without a solutions engineer walking them through it. For partner-facing APIs behind a firewall, authenticated testing extends to private endpoints too, not just public ones. The explorer handles HTTP-based protocols, including REST and server-sent events; gRPC endpoints are documented but executed through their own tooling rather than in the browser.
A reference architecture: one source, three audiences
Putting the steps together produces a single documentation site that serves everyone from one repository:
- The spec carries
x-fern-audiencestags on every endpoint, schema, and sensitive property. - Public content is explicitly marked viewable by everyone and needs no login.
- Partner content is tagged
partnerand gated by a partner role, unlocked through JWT handoff from your portal or SSO. - Internal content is tagged
internaland restricted to employee roles, often on the same pages as public content via section-level access control. - Search and AI answers respect the same roles, so a partner's queries never surface internal endpoints.
That last point is easy to overlook and important to get right. If documentation search or an AI assistant indexes the full content set, it can leak restricted endpoints through answers even when the pages themselves are gated. Access-aware search runs retrieval only against the partitions a reader is permitted to see, so RBAC extends to every discovery surface, not just direct page loads. When you evaluate a platform for partner docs, confirming that its search and AI layer enforces the same permissions is as important as confirming the page-level gate.
Common failure modes to plan for
A few recurring issues trip up partner documentation setups:
- Testing RBAC only in preview. Access control rules generally validate against a live domain, not a local or preview build. Plan to verify gating in production rather than assuming a preview reflects it.
- Forgetting the default-deny behavior. Because unmarked content requires authentication, teams sometimes ship a docs site where nothing is public. Declare the public surface explicitly.
- Leaking fields through examples. Hiding a property in the schema but leaving it in a hand-written example payload defeats the filter. Automatic example scrubbing avoids this, but custom snippets need review.
- Gating the page but not the search index. As above, confirm search and AI answers honor roles before opening a partner tier.
How Fern manages partner-only documentation from one source
Fern generates partner-only API documentation from a single API definition rather than a second portal. Audience filtering through the x-fern-audiences extension shapes what each audience sees down to the property level, and role-based access control gates partner content at the page, section, API-reference, and MDX-block level, backed by JWT, OAuth, SSO, or password authentication. Because the API reference, guides, and SDKs all generate from the same spec, partner docs stay synchronized with the public API instead of drifting, and Fern's access-aware search and Ask Fern assistant enforce the same roles so restricted endpoints never surface to the wrong audience. For teams with strict deployment requirements, Fern also supports self-hosting the documentation behind a VPC.
Final thoughts on partner API documentation
The decision that keeps partner documentation maintainable is to treat access as an attribute of the content, not a reason to fork the site. One API definition, tagged by audience and gated by role, serves public, partner, and internal developers from a single source that never drifts out of sync. A second portal solves the access problem by recreating the maintenance problem, and the gap only widens as more audiences arrive. Audience filtering plus RBAC delivers the same isolation without the duplication. To see audience filtering, role-based access control, and authenticated partner testing working from one source, book a demo.
FAQ
What is partner API documentation?
Partner API documentation is the subset of an API's reference and guides made available to specific external organizations under a formal agreement, rather than to the general public. It typically covers partner-only endpoints, elevated rate limits, and dedicated authentication schemes, and it sits behind access control so only authorized partners can view it. The most maintainable approach serves it from the same source as the public docs, filtered and gated by audience.
How do you create partner-only API docs without a separate site?
Tag each endpoint, schema, and property in the API specification with an audience identifier, then use role-based access control to gate the partner-tagged content behind an authenticated partner role. The documentation platform renders the correct view for each audience from one source, so partners see partner and public endpoints while internal content stays hidden. This avoids the drift and duplicated maintenance of a second portal.
How do you control who can see API documentation for partners?
Access is controlled by combining authentication with role-based access control. Readers authenticate through JWT, OAuth, SSO, or a shared password, and their identity maps to a role that determines which pages, sections, and endpoints they can load. Granular RBAC lets partner-only content coexist with public content on the same page, revealed only to readers whose role permits it.
Can partners test API endpoints directly from the documentation?
Yes. When the documentation injects a partner's API key from their JWT or OAuth session into an interactive API explorer, partners can authenticate and run live calls against REST and server-sent-events endpoints without copying credentials into a separate tool. This enables self-service onboarding, including authenticated testing of endpoints behind a firewall. gRPC endpoints are documented but tested through their own tooling rather than in the browser.
Does documentation search leak restricted partner endpoints?
It can, if the search index and AI assistant are not access-aware. To prevent leaks, the search and AI layer must run retrieval only against the content partitions a reader is permitted to see, so a partner's queries and AI answers never surface internal or other-partner endpoints. Confirming that a platform's search enforces the same roles as its page-level gating is an essential check when evaluating tooling for partner documentation.