Authentication & API keys

The API and MCP authenticate with an API key shaped like durum_sk_live_…. The key carries your account and its permissions; you never need to specify which client you are.

Create a key

1. In DURUM.ai, go to Settings → API keys.
2. Click Create key.
3. Name it (e.g. "Looker Studio", "Personal Claude") and check the desired scopes.
4. Copy the key immediately — it is shown only once. Only its hash is stored; DURUM cannot show it to you again.

To revoke a key, click Revoke next to it. The effect is immediate.

Use the key

Pass the key in the Authorization header:

curl https://app.durum.ai/api/v1/dashboard/kpis \
  -H "Authorization: Bearer durum_sk_live_YOUR_KEY"

Scopes

A key only accesses the scopes you grant it. Read-only by default.

Scope	Grants access to
read:dashboard	Aggregated KPIs (CEO/marketing/sales)
read:ads	Spend, campaigns, performance
read:attribution	Multi-touch attribution, capture health
read:events	CRM events (leads → sales)
read:sales	Sales performance, reps, pipeline, no-show
read:finance	P&L, revenue (margins not exposed)
read:funnel	Funnel stages, conversion
read:contacts	Contacts + attribution
read:calls	Calls: scorecards, transcripts
read:icp	ICP criteria
read:capi	Your connected Meta pixels (tokens excluded)

Write scopes (actions — grant explicitly):

Scope	Allows
write:goals	Update your KPI goals
write:settings	Update your settings (sale rule)
write:icp	Update your ICP criteria
write:ads	Manage your ad rules (enable/disable, dry-run, delete)

write:* scopes must be requested/checked explicitly (never granted by default). Over the MCP connector, a write shows a warning at consent.

The special scope * grants all read scopes.

If a key lacks the required scope, the endpoint returns 403 insufficient_scope.

Limits & logging

• Rate: 600 requests/minute per key (429 beyond, X-RateLimit-* headers).
• Audit: every request is logged (key, endpoint, date).
• Expiry: optional, set at creation time.