Distributing partner documentation as PDFs over email works until it does not. This is what replacing it involved, including a six-week security review that the permission model had to survive.
Three audiences, three tools
The company had public API documentation on a static site generator, partner-specific integration guides distributed as PDFs over email, and internal runbooks in a wiki.
Each had a different failure mode. The public docs were fine but disconnected from everything else. The partner PDFs were the real problem: nobody could say which version a given partner had, and updating a shared section meant regenerating and re-sending 40 documents. The runbooks were current but unfindable.
The trigger was a partner integrating against a specification that had changed four months earlier, because they were working from a PDF sent before the change.
How the separation was set up
One workspace, three projects, three audiences.
The public project holds API reference generated from the OpenAPI specification, quickstarts and conceptual guides. Indexed, open, no sign-in.
The partner project is restricted per partner: each partner's integration guide sits in its own category, visible only to that partner's email domain and named accounts. Shared partner content - certification requirements, settlement timelines - lives in snippets so one edit updates all 40.
The internal project holds runbooks, escalation paths and the settlement reconciliation procedures. SSO-only, with department-level permissions.
- Public: indexed, no sign-in, API reference plus guides.
- Partner: per-partner categories, restricted by domain and named account.
- Internal: SSO-enforced, department permissions, no external access.
- Shared content in snippets across all three, edited once.
The security review
Six weeks and two rounds of questions. Four things carried the discussion.
Data residency: the workspace was created in the India region and pinned contractually.
Permission-aware AI retrieval: the security team's main concern was whether an AI answer could be assembled from content the asker was not entitled to see. They tested it directly - signing in as a partner and attempting to elicit internal settlement detail - and were satisfied that retrieval is filtered before generation rather than after.
SSO enforcement, so password sign-in is disabled entirely for internal users, and the audit log, which they now pull quarterly for access review.
What changed for partners
Partner integration time roughly halved. Two changes account for most of it.
The quickstart was rewritten to get a partner from credentials to first successful sandbox call in under ten minutes, with their own key substituted into every code sample once signed in. Previously most partners opened a support ticket at this stage.
The try-it console against the sandbox removed the second common delay - partners debugging their own HTTP client before they had ever seen a successful response to compare against.
The secondary effect was on the integrations team, who stopped fielding the same three questions and started working on the harder ones.
What they would flag to others
Two things. Setting up 40 partner categories with the right permissions took longer than expected and would have been faster scripted through the API from their existing partner list.
And the snippet library needed governance earlier than they thought: within three months two people had created near-duplicate snippets for the same settlement text, which is exactly the problem snippets exist to prevent.