Keys and tokens
Trail has three kinds of secret. None of them is ever sent to the browser of a visitor.
| Name | Set with | Used for | Can reach |
|---|---|---|---|
| Dashboard password | TRAIL_PASSWORD | Signing in to the dashboard | Everything under /api/*, through a session cookie |
| Session secret | TRAIL_SECRET | Signing the trail_session cookie | Nothing by itself. Set it so sessions survive restarts |
| API token | Settings, or TRAIL_API_TOKENS | Scripts, dashboards and AI assistants | /api/v1/* and /mcp, by scope and site |
The site id in data-site is public by design: it is in your page source. It only decides which site an event belongs to, and events are accepted only from the site's allowed origins.
API tokens
Make a token in the dashboard, or set it in the environment.
In the dashboard. Open Settings → API tokens (or AI assistants, which makes one for you), choose a name, an access level and a site, and click Create token. The secret is shown once. Revoke a token from the same list and it stops working at once.
In the environment.
TRAIL_API_TOKENS="laptop:$(openssl rand -hex 24):read,ci:$(openssl rand -hex 24):write"Each entry is name:token:scope:
- name labels the token. Names must be unique, and cannot reuse a dashboard token's name.
- token is the secret, at least 24 characters, and different for every entry.
- scope is
readorwrite. Thenotesandcrawlscopes are for dashboard tokens only.
The server refuses to start if an entry is malformed, so a typo never leaves you with an open endpoint. Errors name the entry, never the token value. Environment tokens cover every site and are revoked by removing them and restarting.
Scopes
| Scope | Dashboard label | GET /api/v1/* | /mcp | Also allowed |
|---|---|---|---|---|
read | Read stats only | yes | yes | nothing else |
notes | Stats and chart notes | yes | yes | add and delete chart notes at /api/v1/notes |
write | Everything in the API | yes | yes | every POST, PATCH and DELETE on /api/v1/*: goals, funnels, sites and more |
crawl | Crawler logs only | no | no | POST /api/v1/crawls, for trail crawlers import |
Anything else gets 403.
Per site
A dashboard token covers one site or all sites, including ones you add later. A site token cannot read another site: asking for one returns 403. Give assistants and scripts a read token for the one site they need.
Send the token as a header:
curl -H "Authorization: Bearer $TOKEN" https://stats.example.com/api/v1/sitesA missing or unknown token gets 401. Each token may make 300 requests a minute; past that the answer is 429 until the bucket refills.
API tokens cannot sign in to the dashboard, and the dashboard password does not work as a bearer token.
Rotating
Create the new token next to the old one, move your clients over, then revoke the old one in Settings → API tokens. For a token set in TRAIL_API_TOKENS, add the new entry, restart, move over, then remove the old entry and restart again.