API keys and scopes
Every agent of an account has its own keys. A key is sent as a Bearer token on REST and MCP:
Authorization: Bearer mety_live_XXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXFormat
Section titled “Format”mety_live_ + an 8-character public prefix + _ + 32 random base62 characters. The prefix is shown in the app
and in whoami; only sha256(secret) is stored, so Mety can never show a key again. The fixed mety_live_ shape
lets secret scanners recognise a leaked key.
Creating and revoking keys
Section titled “Creating and revoking keys”Keys are created by an owner or admin in Settings → Agents (agents never manage keys). Each key has:
- Scopes: what it can do (below). Default:
records:read records:write feedback:write. - Expiry (optional). After it, the key gets
401 INVALID_API_KEY. lastUsedAt, updated at most once a minute.
Revoking a key, or archiving its agent, takes effect on the next request (401 INVALID_API_KEY). On the Free plan
an account has at most one active key; creating another answers 402 PLAN_LIMIT_REACHED with limit: "apiKeys".
Scopes
Section titled “Scopes”| Scope | Allows | Default |
|---|---|---|
records:read |
Read organizations, contacts, deals, activities, pipelines, custom field definitions, metrics, history, search, export | ✓ |
records:write |
Create, update and archive records, deals, activities and links | ✓ |
records:delete |
Hard-delete records and activities | never |
pipelines:manage |
Create, edit and delete pipelines and stages | |
fields:manage |
Define, edit and delete custom field definitions | never |
feedback:write |
Send feedback to the Mety team | ✓ |
audit:read |
Read the account’s audit log |
A call without the scope it needs gets 403 FORBIDDEN with details.required (for example ["records:write"]).
Do not retry it: ask a person for a key with that scope. Account settings, members, invitations, agents, keys and
billing are never available to an agent, whatever its scopes.
Over MCP, some tools are only listed when the key has their scope: delete_record (records:delete),
list_audit_events (audit:read), the pipeline and stage tools (pipelines:manage) and the custom field write
tools (fields:manage). See the tool catalogue.
Optional headers
Section titled “Optional headers”| Header | Effect |
|---|---|
Mety-Agent-Run: <run id> |
Free text up to 100 characters, written to the audit log with every change. Use one id per run (an import, a nightly check) |
User-Agent |
Recorded with the audit context |
X-Request-Id |
Echoed back; otherwise Mety generates one. Quote it when you report a problem |
Agents never send Mety-Account: the key’s account is implicit and the header is ignored.
Failures
Section titled “Failures”| Situation | Answer |
|---|---|
No Authorization header |
401 UNAUTHENTICATED |
| Wrong, revoked or expired key, or its agent archived | 401 INVALID_API_KEY: stop and ask a person |
An OAuth access token (mety_oat_…) on REST |
401 INVALID_TOKEN: OAuth tokens work only at /mcp |
| Missing scope | 403 FORBIDDEN, details.required |
Keys or OAuth?
Section titled “Keys or OAuth?”Use a key for anything unattended: scheduled agents, imports, cron jobs, the Claude Agent SDK, Claude Code. Use OAuth when a person connects a chat app (Claude.ai, Claude Desktop, ChatGPT, Grok) with Connect → Allow: there is nothing to paste, and it can cover several accounts. See OAuth for MCP connectors.