/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Audience Gating

Audience Gating

Restrict documentation pages to specific client audiences

8 min read

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.

Info

Audience gating is available on every plan.

Overview

With audience gating, you can:

•
Tag pages with audience requirements (e.g., enterprise, beta, otc)
•
Create audience profiles for clients/partners
•
Generate access tokens that unlock gated content
•
Share magic links for frictionless client access

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:

•
Does not appear in the sidebar navigation, previous/next page links or the table of contents — on doc engine v1 and v2 sites alike
•
Does not appear in search results
•
Is never used by the AI assistant when answering questions
•
Is excluded from llms.txt, llms-full.txt, and sitemap.xml
•
Cannot be fetched as raw Markdown (.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.

Note
Fixed: clean URLs were not gated

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
1.
Tag pages — Add audience to page frontmatter
2.
Create profiles — Define audience profiles for each client
3.
Generate tokens — Create access tokens per profile
4.
Share access — Send magic links or raw tokens to clients

Tagging Pages

Add the audience field to any page's frontmatter to restrict access:

yaml
---
title: OTC Trading API
description: Execute over-the-counter trades
audience: [otc]
---

Audience Tag Rules

ConfigurationBehavior
No audience fieldPage 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

yaml
# docs/guides/transfers.mdx
---
title: Transfers Guide
audience: [transfers]
---
yaml
# docs/guides/otc-trading.mdx
---
title: OTC Trading Guide
audience: [otc]
---
yaml
# docs/guides/advanced-setup.mdx
# Only for enterprise customers
---
title: Advanced Setup
audience: [enterprise]
---
yaml
# docs/getting-started.mdx
# No audience field = public page
---
title: Getting Started
---

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:

mdx
## Rate Limits
Standard plans allow 100 requests per minute.
<AudienceGate audience="enterprise">
### Custom Rate Limits
Enterprise plans support custom rate limits. Contact your account manager.
</AudienceGate>

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

1.
Open your project → Settings › Access and scroll to Audiences & tokens
2.
Click New audience
3.
Enter profile details:
•
Name — Display name (e.g., "Acme Corp")
•
Slug — URL-safe identifier (e.g., acme-corp) — immutable after creation
•
Audience tags — comma-separated tags this profile grants access to (e.g. beta, partner)
4.
Click Create audience

An optional description can be set via the API.

Note

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

ProfileSlugAudiences
Acme Corporationacme-corpotc, virtual-accounts
Beta Testersbeta-testersbeta
Enterprise Partnersenterpriseenterprise, transfers, otc, cards

Generating Access Tokens

Each profile can generate access tokens that unlock its assigned audiences.

Via dashboard

1.
Open your project → Settings › Access → Audiences & tokens
2.
Click Show token next to the audience
3.
Copy the access token — readers enter this code to open gated pages, so treat it like a password

Via API

bash
curl -X POST https://api.syntext.dev/v1/projects/:projectId/audiences/:profileId/token \
-H "Authorization: Bearer $SYNTEXT_JWT"

Reading or creating a code needs the admin or owner role. A member gets 403 — see Generate Access Token.

Response:

json
{
"data": {
"token": "K7XQ2M9F",
"audiences": ["otc", "virtual-accounts"]
}
}

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 provide frictionless access — clients click once, and a cookie is set automatically.

Append ?_stx_token=TOKEN to any docs URL, including a clean URL:

text
https://acme-docs.syntext.dev/guides/otc?_stx_token=K7XQ2M9F

When the client visits:

1.
Token is validated
2.
_stx_audience cookie is set (30-day TTL)
3.
Client is redirected to the clean URL

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:

1.
Client visits a gated page without a token
2.
Gate page displays with a token input form
3.
Client pastes their token
4.
Cookie is set and they're redirected to the page

Gate Page

When visitors lack access to a gated page, they see a styled gate page instead. The gate page:

•
Matches your doc site's theme
•
Shows which audiences are required
•
Provides a token input form
•
Displays clear error messages for invalid tokens

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:

bash
curl https://acme-docs.syntext.dev/guides/otc \
-H "x-audience-token: K7XQ2M9F"

API consumers receive JSON error responses:

json
// No token
{ "error": "audience_required", "requiredTags": ["otc"] }
// Invalid token
{ "error": "invalid_audience_token" }
// Wrong audience level
{
"error": "insufficient_audience",
"requiredTags": ["otc"],
"userTags": ["cards"]
}

What Happens at Build Time

Each build reads audience from every page's frontmatter. Once that build is live:

1.
Gated pages are served only to visitors with a matching tag
2.
Gated pages are left out of llms.txt, llms-full.txt, and sitemap.xml
3.
Search and the AI assistant surface gated content only to visitors with access

Best Practices

Use Meaningful Tag Names
Choose clear, product-aligned names like transfers, otc, enterprise rather than generic names like tier1, level2.
Keep Public Pages Public
Don't gate getting-started guides or basic concepts. Only restrict product-specific content.
Overlap Audiences
A page with [otc, transfers] is visible to clients with either tag — use this for shared content.
Revoke access by replacing the profile
A profile's token doesn't expire, and asking for it again returns the same code. To cut someone off — for example when a client relationship ends — delete the profile and create a new one, then share the new link.

Troubleshooting

Client Can't Access a Gated Page

1.
Verify the client's profile has the required audience tag
2.
Check that the profile still exists — deleting a profile stops its token working
3.
Ensure cookies are enabled in their browser
4.
Send the magic link again

Pages Still Visible After Adding Audience Tag

A new or changed audience tag takes effect only after a rebuild:

1.
Commit the frontmatter change
2.
Push to trigger a build
3.
Wait for the build to complete

Token Works in Browser but Not API

Ensure you're sending the token in the x-audience-token header, not as a cookie.

•
Audience Profiles API — Manage profiles via API
•
Configuration Reference — All frontmatter fields
Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext