The v2 API authenticates with personal API tokens. Create one in your
Usertour dashboard under Settings → Personal API keys, then send it as a
Bearer header on every request:
A token is owned by a user and has three properties that gate every request:
- Projects — the token is bound to one or more projects. A request to
/v2/projects/{projectId}/... is rejected unless the token includes that project.
- Scopes — fine-grained capabilities. A request is rejected unless the token
carries the scope its endpoint requires.
- Environments — an optional allowlist. Environment-targeted operations
(publishing, end-user data, sessions, …) are rejected outside it (
E1029);
with no allowlist the token covers every environment of its projects.
The environment allowlist is not a content-isolation boundary. It fences
delivery and end-user data — publishing / unpublishing, users, companies,
sessions, segment membership, analytics, and the environment records themselves
(an out-of-scope environment’s SDK token is withheld). It does not limit
which content a token can see or change: content, versions and themes are
project-level, so any token carrying content scopes can read every piece and
every version in the project — including one that is live in an environment it
may not act on — and can edit or delete them with content:update /
content:delete.So a “staging-only” token still reads (and can rewrite) what is live in
production. If you need someone genuinely walled off from another environment’s
content — a contractor, an agency — put that work in a separate project.
uto_
tokens with the same three properties (granted on the consent screen); they
authenticate REST requests exactly like a personal utp_ token.
Scopes
Grant a token only the scopes it needs.
Two endpoints need no scope at all, only a valid token: GET /v2/me (what this
token may act on) and GET /v2/locales (the locale catalog to file a new
localization under — see Localization).
Localization scopes cover the project’s list of languages. Reading and
writing a content version’s translation is part of the content, so it uses
content:read / content:update. A token with content scopes only can still
find the language codes it may translate into: read the version with
expand=localizations.
Errors
See Errors for the full list.
Using a token with MCP
The MCP endpoint carries no project in its path, so a
token used with MCP must be scoped to exactly one project. Multi-project
tokens work for the REST API but are rejected by MCP tool calls. 
