Guides
View as Markdown Open in ChatGPT Open in Claude

Audience Gating

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 Pro and Enterprise plans.

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 or previous/next page links
  • 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 stripped from the HTML at the edge and excluded from search indexing and AI retrieval.

The only way an unauthorized visitor encounters a gated page is by opening its URL directly — in that case they see an access modal where they can enter an access code.

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:

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

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

# docs/guides/transfers.mdx
---
title: Transfers Guide
audience: [transfers]
---

# docs/guides/otc-trading.mdx
---
title: OTC Trading Guide
audience: [otc]
---

# docs/guides/advanced-setup.mdx
# Only for enterprise customers
---
title: Advanced Setup
audience: [enterprise]
---

# 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 stripped at the edge for visitors without a matching audience tag — the rest of the page stays fully accessible:

## 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. Go to Settings → Audience Gating
  2. Click Create Profile
  3. Enter profile details:
  • Name — Display name (e.g., "Acme Corp")
  • Slug — URL-safe identifier (e.g., acme-corp) — immutable after creation
  • Description — Optional notes
  • Audiences — Tags this profile grants access to
Audience Profiles Dashboard

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

  1. Go to Settings → Audience Gating
  2. Find the profile and click the key icon
  3. Copy the Raw Token or Magic Link Parameter

Via API

curl -X POST https://api.syntext.dev/internal/projects/:projectId/audience/token \
-H "Authorization: Bearer stx_abc12345_..." \
-H "Content-Type: application/json" \
-d '{"profileSlug": "acme-corp"}'

Response:

{
"token": "eyJwcm9qZWN0SWQiOiIxMjM0NSIsInRpbWVzdGFtcCI...",
"audiences": ["otc", "virtual-accounts"]
}

Sharing Access

Magic links provide frictionless access — clients click once, and a cookie is set automatically.

Append ?_stx_token=TOKEN to any docs URL:

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

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:

Gate Page Example

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

API Consumer Access

For non-browser API consumers, send the token via header:

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

API consumers receive JSON error responses:

// No token
{ "error": "audience_required", "requiredTags": ["otc"] }

// Invalid token
{ "error": "invalid_audience_token" }

// Wrong audience level
{
"error": "insufficient_audience",
"requiredTags": ["otc"],
"userTags": ["cards"]
}

Build Pipeline Integration

At build time, Syntext:

  1. Reads audience from each page's frontmatter
  2. Generates _audience.json — maps page slugs to required tags
  3. Uploads the manifest to the CDN
  4. Excludes gated pages from llms.txt, llms-full.txt, and sitemap.xml
  5. Indexes audience tags alongside search documents and AI embeddings so gated content is only surfaced to authorized visitors

The manifest looks like:

{
"guides/otc-trading": ["otc"],
"guides/advanced-setup": ["enterprise"],
"api/virtual-accounts": ["otc", "virtual-accounts"]
}

Best Practices

Choose clear, product-aligned names like transfers, otc, enterprise rather than generic names like tier1, level2.

Don't gate getting-started guides or basic concepts. Only restrict product-specific content.

A page with [otc, transfers] is visible to clients with either tag — use this for shared content.

Generate new tokens periodically and revoke old ones, especially when client relationships change.

Troubleshooting

Client Can't Access a Gated Page

  1. Verify the client's profile has the required audience tag
  2. Check that the token hasn't expired
  3. Ensure cookies are enabled in their browser
  4. Try generating a fresh token and magic link

Pages Still Visible After Adding Audience Tag

Audience gating is enforced at runtime, but the change requires 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.

Was this page helpful?