API authentication and tokens

Create API tokens for the Privatus Analytics REST API, choose permissions, sites, expiry and IP allowlists, and send them as Bearer tokens in requests.

# API authentication and tokens

> Create API tokens for the Privatus Analytics REST API, choose permissions, sites, expiry and IP allowlists, and send them as Bearer tokens in requests.

## API tokens

Create a token in **Workspace settings → API tokens**. Choose:

- a **name**,
- **permissions**: any subset of your own (for example only
  `analytics.read` for a dashboard integration),
- **sites**: all your sites, or only some,
- an optional **expiry date**,
- an optional **IP allowlist** (IPv4/IPv6 addresses or CIDR ranges).

The token (`pat_…`) is shown **once**. We store only a SHA-256 digest and
a short prefix so you can recognize it in the list.

```http
Authorization: Bearer pat_…
```

Requests with a token don't use cookies or CSRF tokens.

## What a token can do

A token acts as the member who created it, narrowed by its settings:

- **permissions** = the member's role ∩ the token's permissions,
- **sites** = the member's site access ∩ the token's sites.

If the member loses access, so does the token. See the
[permission matrix](/docs/teams/roles). Each operation in the
[reference](/docs/api) names the permission it needs.

A token belongs to one workspace. Using it on another workspace's
resources returns `403`.

## Errors

| Status | Code | Meaning |
|---|---|---|
| 401 | `unauthorized` | Missing, invalid, revoked or expired token |
| 403 | `forbidden` | The token's IP allowlist doesn't include your IP, or the token lacks the permission or site |

## Revoking

Revoke a token in the token list. Removing a member from a workspace
revokes their tokens for it. The list shows when each token was last used.

## Public endpoints

A few operations need no token: the docs (including `/docs/*.json`),
`/openapi.json`, and the collection endpoints (`/api/event`, `/api/pixel`,
while `/api/events` uses an [ingest key](/docs/server-side/ingest-keys)).

## OAuth

MCP clients can connect with OAuth 2.1 instead of a pasted token: see
[MCP authentication](/docs/mcp#authentication). OAuth-issued tokens are
ordinary API tokens you can see and revoke in your token list.

以 Markdown 檢視

API tokens#

Create a token in Workspace settings → API tokens. Choose:

a name,
permissions: any subset of your own (for example only analytics.read for a dashboard integration),
sites: all your sites, or only some,
an optional expiry date,
an optional IP allowlist (IPv4/IPv6 addresses or CIDR ranges).

The token (pat_…) is shown once. We store only a SHA-256 digest and a short prefix so you can recognize it in the list.

http

Authorization: Bearer pat_…

Requests with a token don't use cookies or CSRF tokens.

What a token can do#

A token acts as the member who created it, narrowed by its settings:

permissions = the member's role ∩ the token's permissions,
sites = the member's site access ∩ the token's sites.

If the member loses access, so does the token. See the permission matrix. Each operation in the reference names the permission it needs.

A token belongs to one workspace. Using it on another workspace's resources returns 403.

Errors#

Status	Code	Meaning
401	`unauthorized`	Missing, invalid, revoked or expired token
403	`forbidden`	The token's IP allowlist doesn't include your IP, or the token lacks the permission or site

Revoking#

Revoke a token in the token list. Removing a member from a workspace revokes their tokens for it. The list shows when each token was last used.

Public endpoints#

A few operations need no token: the docs (including /docs/*.json), /openapi.json, and the collection endpoints (/api/event, /api/pixel, while /api/events uses an ingest key).

OAuth#

MCP clients can connect with OAuth 2.1 instead of a pasted token: see MCP authentication. OAuth-issued tokens are ordinary API tokens you can see and revoke in your token list.