Prompt
How do I host private API docs for partners?
Latest observation
A good way to host private API docs for partners is to treat them like a product portal: authenticated, versioned, searchable, and easy to revoke access to.
Common options
1) Private docs site behind authentication
Host your docs on a normal docs platform, but put it behind login.
Good for:
- external partner access
- fast setup
- role-based access control
Typical stack:
- Docs content: Markdown / OpenAPI / Markdown site
- Hosting: Vercel, Netlify, S3 + CloudFront, GitHub Pages behind auth proxy
- Auth: SSO, OAuth, Okta, Auth0, Azure AD, Google Workspace, etc.
- Access control: groups/roles per partner
Pros:
- simple
- easy to update
- can be versioned
Cons:
- needs proper auth layer
- search and portal UX depend on your implementation
2) API portal with partner accounts
Use an API management platform that includes developer portal features.
Examples:
- Kong Developer Portal
- Apigee
- Azure API Management Developer Portal
- AWS API Gateway + custom portal
- Postman private workspaces / published docs
Good for:
- larger partner ecosystem
- API keys, onboarding, docs, usage analytics
- self-service registration
Pros:
- integrates docs, auth, keys, analytics
- easier partner onboarding
Cons:
- can be expensive or more complex
- may be overkill for a small partner set
3) Static docs with access via VPN or IP allowlist
Useful for small/internal partner groups.
Good for:
- very small number of trusted partners
- quick secure access
Pros:
- simple security model
- low maintenance
Cons:
- poor UX
- hard to scale
- not ideal for distributed partners
Recommended setup for most teams
If you want something practical and secure:
-
Write docs in Markdown/OpenAPI
- Use a docs generator like Docusaurus, Mintlify, ReadMe, Redoc, Stoplight, or custom static site.
-
Host it privately
- Put the site behind auth using:
- SSO (best for enterprise partners)
- Auth0/Okta login
- Signed-in access via reverse proxy
- VPN or IP restrictions as an extra layer
- Put the site behind auth using:
-
Create partner-specific access
- Separate teams/groups
- Limit docs by partner if needed
- Use expiring invitations and easy revocation
-
Version your docs
/v1,/v2, or version switcher- clearly mark deprecated endpoints
-
Track access
- basic analytics, audit logs, login history
-
Secure the docs themselves
- no secret examples
- redact credentials
- make sample tokens obviously fake
- avoid exposing internal endpoints
Security best practices
- Use HTTPS only
- Require authentication for all pages, not just the root
- Prefer SSO or short-lived tokens over shared passwords
- Use least-privilege access per partner
- Rotate and revoke access easily
- Log access attempts and downloads
- Don’t embed real API secrets in examples
- Consider watermarking exports or PDFs if partners can download them
- If docs include interactive “Try it” consoles, use sandbox credentials
If you need a simple architecture
A common pattern is:
- Docs app: Docusaurus / Redoc / Mintlify
- Hosting: Vercel or AWS S3 + CloudFront
- Auth: Auth0 or Okta
- Gateway: Nginx / Cloudflare Access / AWS ALB auth
- Docs source: Git repo
- Publishing: CI/CD on merge
This gives you private access, easy updates, and control over who sees what.
Choose based on your situation
- Few partners, simple needs: private static site + SSO or VPN
- Many partners, onboarding flow: API portal/developer portal
- Need analytics, keys, usage plans: API management platform
- Need docs only, fast launch: docs site behind auth proxy
If you want, I can suggest a specific setup based on your stack, like:
- AWS
- Azure
- GCP
- Vercel/Netlify
- self-hosted/Nginx
- enterprise SSO with Okta/Auth0