# API tokens and roles

> Account tokens act for a whole workspace; site tokens are limited to one site. How to create, scope, store and revoke them.

Section: CLI, MCP and API  
Canonical page: https://statsy.co/docs/developers/api-tokens  
Last updated: 2026-09-15

Tokens live in **Site settings › API tokens**. Only a signed-in person can create or revoke one — a token can never mint another token.

## Two kinds of token

|  | Site token | Account token |
| --- | --- | --- |
| Prefix | `st_` | `sta_` |
| Scope in the UI | This site | Whole account |
| Reaches | Exactly one site | Every site in the workspace |
| Acts as | Editor | Owner |
| Who can create it | Owners and editors | Owners only |
| Works with the CLI and MCP | No | Yes |

A site token asked for another site gets `403 forbidden` with “Token is scoped to another site”. It also cannot touch workspace settings or the team.

## Create one

Give the token a name you will recognise later, pick the scope, and copy the value from the dialog. It is shown once. Statsy stores a SHA-256 hash and the first few characters, which is what the token list displays.

```bash
curl -H "Authorization: Bearer sta_your_token" \
  https://statsy.co/api/v1/sites
```

## Roles

Roles apply to people and tokens alike. **Owners** can do everything, including billing, the team, and deleting a site. **Editors** can create and change sites, goals, funnels, alerts, integrations and share links. **Viewers** can read.

On the API this means any non-`GET` request to a site route needs owner or editor, and a viewer gets `403 forbidden` with “Viewers cannot change this site”. Some things are deliberately out of reach for every token: managing tokens, billing, and the team all require a signed-in session and answer `403 session_required` otherwise. See [Team and roles](https://statsy.co/docs/account/team-and-roles).

## Lifetime and revoking

Tokens do not expire. The list shows when each was last used, updated at most once a minute, which makes an unused token easy to spot. Revoking is immediate: the token stops working on the next request and cannot be restored. Account tokens can only be revoked by an owner.

> **Watch out.** If a token may have leaked, revoke it first and create a replacement second. Resetting your password also signs out every session and revokes every connected AI app grant, but it does not revoke API tokens.

## Storing tokens safely

- Keep tokens in environment variables or a secret manager, never in a repository or a client-side bundle.
- Use a site token when a script only needs one site. It is the smaller blast radius.
- Create one token per system, so you can revoke just that system.
- The CLI already stores its token at `~/.statsy/config.json` with owner-only permissions.

Previous: [MCP server for AI assistants](https://statsy.co/docs/developers/mcp)  
Next: [REST API overview](https://statsy.co/docs/developers/api)