Audience Gating
Restrict documentation pages to specific client audiences
Audience gating lets you control which documentation pages are visible to different client segments. This is essential for B2B platforms that serve multiple clients with different product access levels.
Audience gating is available on every plan.
Overview
With audience gating, you can:
enterprise, beta, otc)Pages without audience tags remain public and visible to everyone.
Hidden by Default
Gated content is invisible to visitors without a matching access token — not just blocked. Until a valid token is presented, a gated page:
llms.txt, llms-full.txt, and sitemap.xml.md exports are gated too)The same applies to <AudienceGate> sections inside public pages — gated sections are removed from the page and its table of contents before it's served, left out of the page's .md copy, llms-full.txt, a changelog's Atom feed and search results, and used in AI answers only for visitors with access. A gate with no audience is hidden from everyone.
The only way an unauthorized visitor encounters a gated page is by opening its URL directly — in that case they see the gate page, where they can enter an access code.
The gate applies to every URL a page is served at — the clean URL readers
use (/guides/otc, /guides/otc/) as well as /guides/otc.html and the
.md export. Every page of a deploy that contains gated content is served
with private caching, so a shared cache never hands one reader's view to
another.
Before 13 November 2026 the gate only ran for URLs ending in .html or
.md, so a gated page's clean URL served it to anyone, and clean-URL pages
kept gated sidebar links and sections. Both are fixed for every site with no
rebuild needed.
How It Works
flowchart LR
A[Page Request] --> B{Gated Page?}
B -->|No| C[Serve Page]
B -->|Yes| D{Has Token?}
D -->|No| E[Show Gate Page]
D -->|Yes| F{Valid Token?}
F -->|No| E
F -->|Yes| G{Audience Match?}
G -->|No| E
G -->|Yes| C
audience to page frontmatterTagging Pages
Add the audience field to any page's frontmatter to restrict access:
Audience Tag Rules
| Configuration | Behavior |
|---|---|
No audience field | Page is public (visible to everyone) |
audience: [] | Page is public (empty array = no restrictions) |
audience: [tag] | Page requires the specified tag |
audience: [tag1, tag2] | Page visible if client has any matching tag |
Example: Multi-Product Docs
Gating Sections Within a Page
Use the <AudienceGate> component to restrict a section of an otherwise public page. The section is removed before the page is served to visitors without a matching audience tag — the rest of the page stays fully accessible:
Multiple tags are supported (audience="beta, enterprise") — the section is visible if the visitor has any matching tag. Section gating and frontmatter gating can be combined on the same page.
See the Audience Gate component reference for full details.
Managing Audience Profiles
Audience profiles are managed in the dashboard or via the API.
Dashboard setup
acme-corp) — immutable after creationbeta, partner)An optional description can be set via the API.
Settings › Access replaced the old Audiences, Access control add-on, and collaboration access screens in Dashboard 2.0 — site visibility, page rules, IP allowlist, audiences, and the access log now live on one page.
Example Profiles
| Profile | Slug | Audiences |
|---|---|---|
| Acme Corporation | acme-corp | otc, virtual-accounts |
| Beta Testers | beta-testers | beta |
| Enterprise Partners | enterprise | enterprise, transfers, otc, cards |
Generating Access Tokens
Each profile can generate access tokens that unlock its assigned audiences.
Via dashboard
Via API
Reading or creating a code needs the admin or owner role. A member gets 403 — see Generate Access Token.
Response:
The token is an eight-character code drawn from an alphabet with no 0/O
or 1/I/L, so it can be read out over a call or typed from a note. It is
generated on the first request for a profile and stored; asking again returns
the same code rather than issuing a new one. Codes are unique within a
project, so two projects may hold the same one — a code only ever unlocks
the project it was issued for.
Tokens issued before short codes shipped are longer base64 strings. They are still accepted, and you do not need to reissue them.
Sharing Access
Magic Links (Recommended)
Magic links provide frictionless access — clients click once, and a cookie is set automatically.
Append ?_stx_token=TOKEN to any docs URL, including a clean URL:
When the client visits:
_stx_audience cookie is set (30-day TTL)Subsequent visits to any gated page work without re-entering the token. Once the cookie is set, gated pages also appear in the sidebar navigation and search results, and the AI assistant can use them when answering questions.
Raw Token
Clients can also paste tokens directly on the gate page:
Gate Page
When visitors lack access to a gated page, they see a styled gate page instead. The gate page:
After a valid token, the gate only redirects to a path on the same site.
On doc engine v2
On a doc engine v2 site, the gate is drawn in the site's own preset — its header, sidebar, accent and fonts — instead of the standard gate page. It shows the gated page's title, its breadcrumb and the name of the audience it needs, with the access-code form. The page's headings are not shown, and gated pages are left out of the gate's own sidebar.
A v2 site picks this up on its next build — until it rebuilds, it gets the standard gate page. v1 sites keep the standard gate page.
Sign-in page and the assistant
/_audience-auth?redirect=/some/path serves the same access-code form on its
own, then returns the reader to redirect (same-site paths only). It's sent
private, no-store, noindex, and can't be framed by other sites.
The agent mode assistant links to it when the gated pages notice is on (off by default): a reader who isn't signed in learns that pages for signed-in readers matched their question — never which pages or what they say — and can Sign in. Answers never use gated pages the reader can't see.
API Consumer Access
For non-browser API consumers, send the token via header:
API consumers receive JSON error responses:
What Happens at Build Time
Each build reads audience from every page's frontmatter. Once that build is live:
llms.txt, llms-full.txt, and sitemap.xmlBest Practices
transfers, otc, enterprise rather than generic names like tier1, level2.[otc, transfers] is visible to clients with either tag — use this for shared content.Troubleshooting
Client Can't Access a Gated Page
Pages Still Visible After Adding Audience Tag
A new or changed audience tag takes effect only after a rebuild:
Token Works in Browser but Not API
Ensure you're sending the token in the x-audience-token header, not as a cookie.