Master this essential documentation concept
A documentation architecture where different user groups such as the public, partners, and internal teams each have access to separate, permission-appropriate layers of content.
A documentation architecture where different user groups such as the public, partners, and internal teams each have access to separate, permission-appropriate layers of content.
Many teams first define their multi-tier access architecture during onboarding sessions, recorded all-hands meetings, or internal training calls. Someone walks through which content layers exist, who sees what, and why — but that knowledge lives inside a video file that the wrong audience may not even be able to find, let alone access appropriately.
This creates a real structural problem. A video explaining your multi-tier access model is itself undifferentiated — it either exists or it doesn't. You can't easily restrict a specific timestamp to partners while making another section public. The content that describes your access layers ends up ignoring them entirely.
Converting those recordings into structured documentation changes that dynamic. When your video walkthroughs become searchable, text-based docs, you can organize the output to match your actual multi-tier access model — publishing the partner-facing overview in one permission layer, keeping internal implementation notes in another, and surfacing only the public-appropriate summary externally. A concrete example: a recorded onboarding call that covers both internal admin workflows and partner API access can be transcribed and split into two separate documents, each living in the correct tier.
If your team regularly records sessions that touch on access-sensitive content, exploring a structured approach to video-to-documentation conversion is worth your time.
A SaaS company publishes all API documentation publicly, exposing premium endpoint specs, rate-limit tiers, and partner-only webhook schemas to competitors and free-tier users who cannot access those features anyway.
Multi-Tier Access splits the API reference into a public tier (core REST endpoints), a partner tier (advanced webhooks, bulk APIs, SLA guarantees), and an internal tier (admin override endpoints, billing API), each gated by the appropriate credential level.
['Audit all existing API docs and tag each page with one of three permission labels: public, partner, or internal.', 'Configure the documentation platform (e.g., ReadMe.io or Stoplight) to require an OAuth token or API key scope to unlock partner and internal sections.', 'Integrate the partner portal login with SSO so that approved partners automatically see the partner tier upon sign-in without manual provisioning.', "Add a visible 'Request Partner Access' CTA on public pages that describe locked features, routing users to the partner onboarding form."]
Competitor scraping of premium API specs drops to zero, partner onboarding support tickets decrease by 40% because partners find their integration docs in one authenticated space, and internal engineers stop accidentally sharing admin endpoint links externally.
A health-tech company stores public patient-portal help articles and internal HIPAA compliance runbooks in the same Confluence space, creating audit failures and the constant risk that a misconfigured page permission exposes PHI handling procedures to unauthenticated users.
Multi-Tier Access establishes three isolated documentation spaces: a public-facing help center (Zendesk), a partner tier for EHR integration guides (authenticated partner portal), and an internal tier for HIPAA runbooks and incident response procedures (Confluence with Okta SSO enforcement).
['Migrate all public help articles to a Zendesk Help Center configured with no authentication requirement and no links back to internal tools.', 'Create a dedicated partner documentation portal in Confluence with a separate space, restricting access to groups mapped to verified integration partners via Okta group sync.', "Lock the internal HIPAA runbook space to the 'Engineering-Internal' and 'Compliance' Okta groups, enabling audit logging on every page view for SOC 2 evidence.", 'Establish a quarterly access review process where space admins certify that no partner or public users have been granted internal-tier permissions.']
The company passes its next HIPAA audit with zero findings related to documentation access, and the security team can produce a full access log showing exactly who viewed the incident response runbooks during a breach simulation.
An open-source project with a commercial enterprise edition keeps all documentation in a single public GitBook, meaning enterprise-only features like SSO configuration and audit log APIs are visible to community users who cannot use them, generating confused GitHub issues and support tickets.
Multi-Tier Access creates a public GitBook space for community documentation and a separate, authenticated GitBook organization for enterprise customers, with internal engineering notes kept in a private GitHub wiki gated by org membership.
["Fork the existing public GitBook into two spaces: 'Community Docs' (public) and 'Enterprise Docs' (invite-only), copying only the relevant pages to each.", 'Configure the Enterprise Docs space to require a GitBook account linked to a verified enterprise customer email domain, provisioned automatically when a license is issued.', "Add prominent banners on community pages that describe enterprise features, linking to a 'Learn about Enterprise' landing page rather than the locked documentation directly.", 'Set up a GitHub Action that syncs the internal engineering wiki from a private repo, ensuring it is never accidentally published to either public-facing space.']
Community GitHub issues referencing enterprise-only features drop by 60%, enterprise customers report faster self-service onboarding because their docs are no longer buried among community content, and the support team can point customers to tier-appropriate resources instantly.
A brokerage platform's developer portal exposes institutional-grade API documentation—including FIX protocol specs, direct market access endpoints, and co-location setup guides—to retail developers who lack the regulatory approval and capital requirements to use them, creating compliance and liability risks.
Multi-Tier Access gates institutional API documentation behind a KYC-verified partner tier, so retail developers see only the standard brokerage API, while institutional clients authenticated via client certificate see the full FIX and DMA documentation in a separate portal section.
['Classify all API documentation into three tiers: Retail (OAuth 2.0 standard flow), Institutional (client certificate + compliance approval flag in the identity provider), and Internal (VPN + employee SSO only).', "Implement attribute-based access control (ABAC) in the developer portal so that the 'institutional_approved' claim in the JWT automatically unlocks the institutional documentation section upon login.", 'Add a compliance gate in the onboarding flow: institutional docs remain hidden until the compliance team marks the account as approved in the CRM, which triggers a webhook to update the identity provider claim.', 'Audit access logs monthly, cross-referencing documentation views against active institutional agreements to ensure no lapsed clients retain access to DMA specs.']
The compliance team achieves full auditability of who accessed institutional trading documentation, eliminating a regulatory gap identified in the previous year's internal audit, and retail developer confusion about unavailable endpoints drops measurably in support ticket volume.
Attempting to retrofit access controls onto an existing flat documentation structure leads to miscategorized pages and permission gaps. Establish a clear taxonomy—such as Public, Partner, and Internal—with written criteria for what qualifies each page for a given tier before touching a single document. This upfront design prevents the most common failure mode: content that is technically locked but logically belongs in the wrong tier.
Manually managing which users can see which documentation tier is error-prone and creates stale access when employees change roles or partners lose their agreements. Connecting your documentation platform to an identity provider (Okta, Azure AD, Auth0) and driving access from group membership ensures that a partner who loses their contract automatically loses documentation access when removed from the partner group. This also enables just-in-time provisioning for new users.
Hiding the existence of higher-tier documentation entirely frustrates users who need to understand what capabilities exist before requesting access. A partner who cannot find any mention of the bulk import API may never know to ask for it, stalling their integration. Showing locked content titles and brief descriptions with a clear access request path converts documentation discovery into a business opportunity and reduces misdirected support tickets.
Documentation access permissions drift over time as team members change roles, partnerships expire, and new content is added without proper tier assignment. A quarterly audit process that generates a report of all users per tier, cross-referenced against active contracts and employment records, catches over-privileged access before it becomes a security or compliance incident. Automating this report from your IdP and documentation platform APIs makes the audit practical rather than a manual burden.
When a product releases a new version, the access tier for documentation about that version's features may differ from the previous version—a feature that was partner-only in v2 may become public in v3. Treating permission tiers as metadata that travels with the content version, rather than a global setting, prevents the common problem of a public v3 page accidentally linking to a still-locked v2 partner page for background context. This is especially critical in docs-as-code workflows using Git.
Join thousands of teams creating outstanding documentation
Start Free Trial