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.
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.
curl -H "Authorization: Bearer sta_your_token" \
https://statsy.co/api/v1/sitesRoles
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.
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.jsonwith owner-only permissions.
Last updated · Markdown version