API tokens and permissions
Last updated
An API token lets a script, a CI job or an AI assistant act for you in one workspace, without signing in. Use one with the query API and the MCP server. A token can only do what you chose when you made it, and never more than you can do yourself. Write keys (mk_pub_…), which only send events, are different: see Install Metrickle.
Make a token
- In the dashboard, open Connect AI and go to Create a token.
- Give it a name that says where you'll use it, such as "Nightly export job".
- Choose the workspace. The token works only there.
- Choose its access: Read only, Read and draft, or Custom to pick each permission.
- Choose when it expires: 30 days, 90 days, 1 year or never.
- Copy the token. It starts with
mk_sk_and is shown once. Metrickle keeps only a hash of it.
Send it as a bearer token:
Authorization: Bearer mk_sk_…
You can have up to 20 active tokens. Making one is recorded in the workspace's audit log. If the workspace requires single sign-on or two-step verification, you need to be signed in that way to make a token.
Access presets
| Preset | What it includes |
|---|---|
| Read only | Every read permission a token can carry, for analytics, funnels, tasks, friction, surveys and feedback |
| Read and draft | Read only, plus adding apps, drafting goals, funnels, tasks, surveys and studies, and working cases. Drafts stay drafts until a person acts on them |
| Custom | The permissions you pick from the list below |
A preset only includes permissions your own role has in that workspace.
Permissions a token can carry
| Permission | Allows |
|---|---|
team.read | See members, invites and roles |
plan.read | See the plan and usage |
audit.read | See and export the audit log |
apps.read | See apps |
apps.create | Add apps |
analytics.read | See analytics, goals, funnels and protected tasks |
goals.edit | Add, change and remove goals |
funnels.edit | Add, change and remove funnels |
tasks.draft | Draft tasks, and change or discard drafts |
cases.work | Open cases, draft fixes, mark shipped, verify |
research.read | See surveys, feedback and heatmaps |
surveys.edit | Draft surveys, and change drafts |
feedback.triage | Change feedback status |
studies.draft | Draft studies |
recordings.read | Watch session replays and see feedback screenshots |
participants.read | See study participants' details |
data.export | Export raw events, with user ids and properties |
releases.manage | Add and remove releases |
issues.create | File issues in a connected tracker |
The read permissions in this list are team.read, plan.read, audit.read, apps.read, analytics.read, research.read, recordings.read, participants.read and data.export.
What only a person can do
Some permissions are never given to a token, whatever the token or your role says. These are promises and switches a person makes in the dashboard:
| Permission | Allows |
|---|---|
team.invite | Invite people |
team.manage | Change members' roles and app access, remove members |
roles.manage | Create and edit custom roles |
billing.manage | Choose the plan, manage payment details and invoices |
support.history | See Metrickle support sessions |
workspace.owner | Make other people owners |
security.manage | Set up single sign-on, SCIM, verified domains and security policies |
apps.settings | Change app settings |
apps.keys | See and rotate write keys and hook URLs |
apps.delete | Delete apps |
data.erase | Erase a visitor's data |
tasks.hold | Protect tasks, and change or delete protected ones |
cases.dismiss | Dismiss cases |
surveys.launch | Put surveys live, change or delete them |
feedback.delete | Delete feedback |
research.settings | Change research settings |
studies.run | Change, recruit for and close studies, record verdicts |
participants.manage | Add and update participants |
warehouse.manage | Set up the scheduled warehouse export and its bucket credentials |
integrations.manage | Set up Slack, Teams, webhooks and revenue sources |
trackers.manage | Connect issue trackers |
A token also can't make or revoke tokens.
A token never does more than you can
Every request with a token is checked against what you can do in the workspace at that moment, narrowed to the permissions the token was made with:
- If your role changes, your tokens change with it. Lose a permission and your tokens lose it too, even if they were made with it.
- If you leave the workspace, your tokens stop working there.
- If you can only see some of the workspace's apps, so can your tokens.
- If the workspace limits access to certain IP addresses, that applies to tokens too.
A request the token isn't allowed to make gets a 403. The error is not_allowed_for_api_tokens when you could do it yourself but the token can't, and forbidden when you can't either. Protecting a task, for example, returns assistants_cannot_hold_contracts. To understand roles, see team and access.
Revoke a token
Under Connect AI → Your tokens, choose Revoke next to the token. It stops working at once, and anything using it gets 401 invalid_token. Each token shows when it was last used, which helps you find ones you no longer need.
Assistants that sign in instead
Most AI assistants can sign in with your Metrickle account instead of using a token. They're listed under Connect AI → Connected assistants, follow the same rules, and stop working after 30 days unused. See Connect AI assistants over MCP.