API reference
Authentication and access tokens
Every API, MCP and CLI request sends a key as Authorization: Bearer …. There are two kinds of key.
| Key | Use it for |
|---|---|
| Site secret key (ana_sec_…) | Your server, for one website: sending events, payments and identify calls, reading that website's reports and deleting a person's data. Shown once when you add the website. |
| Account access token (mr_…) | The CLI, AI assistants (MCP) and scripts that work across your websites. Acts as you, limited to the scopes and websites you choose. Create it in Settings → API & MCP. |
Create an access token
Open Settings → API & MCP
In the dashboard, click API in the top bar, or go to metricraven.com/app/api.
Name it and choose its access
Use one token per tool, so you can delete one without breaking the others.
Copy the token
It is shown once. Store it in your password manager or an environment variable such as
METRICRAVEN_TOKEN.
Scopes
| Scope | Allows |
|---|---|
| read (always on) | All reports: traffic, breakdowns, revenue, goals, funnels, insights, Search Console, AI crawlers, realtime and chart notes. Customer names and emails are removed. |
| visitors | Visitor search and journeys, and names, emails and visitor IDs inside reports. |
| write | Add websites and chart notes, and change settings, funnels and segments through the API. Tokens can never delete a website or a person's data. |
A token can be limited to chosen websites. Only tokens for all websites can create new ones. If you lose access to a website, every token you created loses it too.
Use a token
Report endpoints need the website, passed as site. Find website IDs with GET /api/v1/websites.
terminal
curl 'https://metricraven.com/api/v1/stats/traffic?site=YOUR_SITE_ID&range=all' \
--header "Authorization: Bearer $METRICRAVEN_TOKEN"Errors
| Status | Meaning |
|---|---|
| 401 unauthorized | Missing, deleted or mistyped key, a website the token can't use, or a scope it doesn't have. |
| 402 | Your plan's limit was reached, for example the number of websites. |
| 429 | Too many requests. Wait a minute and retry. |
Never put a site secret key or an access token in browser code, a public repository or a URL.
Details
- Only a hash of each key is stored. A lost token can't be shown again: delete it and create a new one.
- Tokens don't expire. The list in Settings shows when each one was last used, so you can delete ones you no longer need.
- Event, payment and identify ingestion always uses the site secret key, not account tokens.