Preview Access
Control who can view preview deployments with shareable links and expiring access tokens.
Overview
Preview deployments let your team review documentation changes before they go live. By default, preview deployments require authentication -- only members of your organization can view them. For external reviewers (clients, contractors, partners), you can generate shareable links with expiring access tokens.
How Preview Auth Works
When preview authentication is enabled (the default), HolyDocs checks every request to a preview deployment:
- If the viewer is an authenticated org member, access is granted
- If the request includes a valid, non-expired preview token, access is granted
- Otherwise, the viewer sees a login prompt or "Access denied" page
Preview authentication only applies to non-production environments. Production deployments use the access level configured in their environment settings.
Enabling Preview Auth
Preview authentication is enabled by default for all new projects. You can toggle it in the dashboard:
Open Preview Access settings
Navigate to Settings > Preview Access in your project dashboard.
Toggle authentication
Enable or disable Require authentication for preview deployments. When disabled, all preview deployments are publicly accessible.
Disabling preview auth makes all preview deployments publicly accessible. This means draft content, unreleased features, and work-in-progress documentation can be viewed by anyone with the URL.
Shareable Links
Shareable links let you give time-limited access to a specific preview deployment without requiring the viewer to log in. Each link contains an embedded access token that expires automatically.
Generating a Shareable Link
Dashboard
Open Preview Access
Navigate to Settings > Preview Access in your project dashboard.
Select a deployment
Choose the preview deployment you want to share from the dropdown. The list shows your 10 most recent deployments.
Set expiration
Choose how long the link should remain valid.
Add a label (optional)
Give the link a descriptive label like "Client review - v2.0" or "Design team feedback" to help you track who has access.
Generate link
Click Generate Link. The shareable URL is copied to your clipboard.
API
bashcurl -X POST "https://api.holydocs.com/api/v1/projects/PROJECT_ID/preview-tokens" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "deploymentId": "dep_abc123", "expiration": "7d", "label": "Client review" }'
Response:
json{ "data": { "id": "ptk_xyz789", "deploymentId": "dep_abc123", "label": "Client review", "shareUrl": "https://preview-abc123.holydocs.com?token=ptk_xyz789...", "expiresAt": 1712534400000, "createdAt": 1711929600000 }}
Expiration Options
| Duration | Use Case |
|---|---|
| 1 hour | Quick review during a meeting or call |
| 24 hours | Overnight review or async feedback |
| 7 days | Sprint review cycle |
| 30 days | Extended review period or client feedback |
Choose the shortest expiration that fits your review workflow. You can always generate a new link if the reviewer needs more time.
Managing Active Tokens
Listing Tokens
The Preview Access settings page shows all active (non-expired, non-revoked) tokens with:
- Label and creation date
- Associated deployment
- Expiration countdown
- Creator name
API
bashcurl "https://api.holydocs.com/api/v1/projects/PROJECT_ID/preview-access" \ -H "Authorization: Bearer YOUR_API_KEY"
Revoking a Token
Revoke a token immediately to remove access, even before it expires:
Dashboard
Click the trash icon next to any active token on the Preview Access settings page.
API
bashcurl -X DELETE "https://api.holydocs.com/api/v1/projects/PROJECT_ID/preview-tokens/TOKEN_ID" \ -H "Authorization: Bearer YOUR_API_KEY"
Revoking a token takes effect immediately. Anyone using the shareable link will see an "Access expired" page on their next navigation.
What Viewers See
When a viewer opens a shareable link:
- The preview deployment loads with full functionality (search, navigation, AI assistant)
- A subtle banner indicates they are viewing a preview deployment
- The AI assistant only has access to content in the preview deployment, not production
- Feedback submitted from preview deployments is tagged as "preview feedback" in your dashboard
When a token expires or is revoked:
- The next page navigation shows an "Access expired" message
- The viewer is prompted to request a new link from the project owner
- No documentation content is visible
Security Considerations
Each token grants access to one specific deployment. If you deploy new changes, existing tokens do not automatically grant access to the new deployment. Generate new tokens for new deployments.
Once a token is created, its expiration is fixed. If a reviewer needs more time, revoke the old token and generate a new one.
The shareable URL includes the token directly. Treat it like a password -- share it over secure channels (DM, email) and avoid posting it in public Slack channels or issue trackers.
Creating, revoking, and using preview tokens generates audit log entries. Org admins can review the full history in Settings > Audit Logs.
Combining with Environments
Preview access works alongside environments. The typical setup is:
| Environment | Access | Preview Tokens |
|---|---|---|
| Production | Public | Not needed |
| Staging | Org members | Use tokens for external reviewers |
| Feature branches | Creator only | Use tokens to share with team |
See Environments for details on configuring access levels per environment.
Plan Requirements
| Feature | Free | Starter | Pro | Business |
|---|---|---|---|---|
| Preview auth toggle | Yes | Yes | Yes | Yes |
| Shareable links | -- | 5 active | 25 active | Unlimited |
| Custom expiration | -- | 24h, 7d | All durations | All durations |
| Audit logging | -- | -- | Yes | Yes |
Best Practices
- Use labels consistently -- Label tokens with the reviewer's name or team. This makes the active tokens list easy to manage.
- Revoke tokens after review -- Don't wait for expiration. Revoke tokens once feedback is collected.
- Prefer short expirations -- Default to 24 hours and extend only when needed.
- Audit periodically -- Review active tokens weekly to ensure only intended reviewers have access.