> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertour.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Personal API tokens, scopes, and project access.

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:

```
Authorization: Bearer utp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

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.

<Warning>
  **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**.
</Warning>

Connections authorized over [MCP OAuth](/api-reference-v2/mcp) hold `uto_`
tokens with the same three properties (granted on the consent screen); they
authenticate REST requests exactly like a personal `utp_` token.

## Scopes

| Scope                | Grants                                                    |
| -------------------- | --------------------------------------------------------- |
| `content:read`       | Read content and versions                                 |
| `content:create`     | Create / duplicate content, create draft versions         |
| `content:update`     | Edit drafts (steps, rules, theme, body), restore versions |
| `content:delete`     | Delete content                                            |
| `content:publish`    | Publish / unpublish a version to an environment           |
| `theme:read`         | List / get themes                                         |
| `theme:create`       | Create themes                                             |
| `theme:update`       | Update themes                                             |
| `theme:delete`       | Delete themes                                             |
| `user:read`          | Read end-users (and their event history)                  |
| `user:write`         | Create or update end-users                                |
| `user:delete`        | Delete end-users                                          |
| `company:read`       | Read companies (and their event history)                  |
| `company:write`      | Create / update companies and manage memberships          |
| `company:delete`     | Delete companies                                          |
| `session:read`       | Read content sessions                                     |
| `session:manage`     | End or delete content sessions                            |
| `attribute:read`     | Read attribute definitions                                |
| `attribute:create`   | Create attribute definitions                              |
| `attribute:update`   | Update attribute definitions                              |
| `attribute:delete`   | Delete attribute definitions                              |
| `event:read`         | Read event definitions                                    |
| `event:create`       | Create event definitions                                  |
| `event:update`       | Update event definitions                                  |
| `event:delete`       | Delete event definitions                                  |
| `segment:read`       | List / get segments                                       |
| `segment:create`     | Create segments                                           |
| `segment:update`     | Update segments and manage manual members                 |
| `segment:delete`     | Delete segments                                           |
| `analytics:read`     | Read analytics data                                       |
| `environment:read`   | List / get environments                                   |
| `environment:manage` | Create / rename / delete environments                     |

Grant a token only the scopes it needs.

## Errors

| Situation                       | Status | Code    |
| ------------------------------- | ------ | ------- |
| Missing `Authorization` header  | 401    | `E1010` |
| Unknown / invalid token         | 403    | `E1000` |
| Token not scoped to the project | 403    | `E1011` |
| Token lacks the required scope  | 403    | `E1012` |

See [Errors](/api-reference-v2/errors) for the full list.

## Using a token with MCP

The [MCP endpoint](/api-reference-v2/mcp) 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.