# 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.