Skip to content

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_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

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.

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".

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.

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.

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

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.