/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Generate Access Token

Generate Access Token

Get or create the access code for an audience profile

POST/v1/projects/{projectId}/audiences/{profileId}/tokenTry it
Session token

Returns the access code for an audience profile, creating it on the first call. The code unlocks every page whose audience tags match the profile's tags.

Note

This endpoint returns a credential. The access code is what unlocks gated documentation for this audience, so treat the response like a password: it is not a public identifier.

Requires the admin or owner role and a session JWT. A member of the workspace gets 403 forbidden with details.requiredRole: "admin". A project you cannot see returns 404, and one whose organization you do not belong to returns 403 — see Authentication and Errors.

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID.
profileId:stringpathRequired
The audience profile ID.

Request Body

None. The code does not expire and carries no label, so there are no options to send.

Response

NameDescription
data.token:string
The profile's access code — eight characters from an alphabet with no 0/O or 1/I/L, so it can be read out or typed from a note.
data.audiences:string[]
The audience tags this code unlocks.

Each profile has one code, and calling again returns it. The first call generates and stores a code. Later calls return the same code rather than issuing a new one, so this endpoint also re-reads an existing code. Admins and owners can also read it as accessToken on List Audience Profiles. Codes are unique within a project. Codes issued before short codes shipped are longer strings. They still work and are returned unchanged.

Error Responses

403 Forbidden

Returned when you are a member of the workspace but not an admin or owner.

json
{
"error": {
"code": "forbidden",
"message": "Only workspace admins can view or create audience access codes.",
"details": { "requiredRole": "admin", "currentRole": "member", "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

404 Not Found

Returned when the profile does not exist in this project.

Sharing the code

Build a magic link by appending ?_stx_token=CODE to any page URL on your doc site — for example https://acme-docs.syntext.dev/guides/otc?_stx_token=K7XQ2M9F. Opening it sets an access cookie, so the reader doesn't have to type the code. Readers can also type the code into the gate page. Non-browser clients send it in the x-audience-token header. See Audience gating for the full flow.

Security notes

•
Anyone holding the code can read the profile's gated pages. Share it only with the people the profile is for.
•
Deleting a profile invalidates its code immediately.
•
Changing the profile's audiences changes what its existing code unlocks.
Was this page helpful? Yes No
Request
bashJavaScriptPythonGoRubyPHPJavaC#bash
curl -X POST https://api.syntext.dev/v1/projects/proj_abc123/audiences/aud_xyz789/token \
-H "Authorization: Bearer $SYNTEXT_JWT"
Responseapplication/json
json
{
"data": {
"token": "K7XQ2M9F",
"audiences": ["otc", "virtual-accounts"]
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext