Skip to main content

API reference

Scopes

What each API key scope allows, defaults and redaction.

Beta. Scopes are live. The list can grow before general availability.

Overview

Every API key carries scopes. A scope decides which endpoints the key may call. Pick them when you create the key in Finn under Settings → Integrations → API keys. Scopes can't be changed on an existing key: create a new key and revoke the old one.

If you are building an AI agent, give it its own key with only the scopes it needs. An agent that reads records and adds notes needs crm:write, nothing else.

The scopes

ScopeAllowsEndpoints
voiceVoice agents and callingEvery endpoint tagged Calls, Finns, Voices, Phone numbers, Audiences, Deployments, Wallet, Do not call
crm:readRead records, kinds, fields and timelinesGET /record_kinds, GET /fields, GET /contacts, GET /contacts/{id}, GET /contacts/{id}/timeline
crm:sensitive:readSee the values of fields marked sensitiveSame reads; without it those values are hidden
crm:writeCreate and update records, add notesPOST /contacts, PATCH /contacts/{id}, POST /contacts/{id}/notes
cases:readRead Finn Operator cases and approvalsGET /cases, GET /cases/{id}, GET /cases/{id}/events, GET /approvals, GET /approvals/{id}
cases:writeStart a casePOST /agents/{id}/cases
approvals:writeDecide an approvalPOST /approvals/{id}/decide, /approve, /reject

A write scope includes the read it builds on:

  • crm:write and crm:sensitive:read include crm:read.
  • cases:write and approvals:write include cases:read.

Defaults

  • A new key with no scope picked gets voice only. A key needs at least one scope.
  • A key created before scopes existed keeps access to every endpoint, with one exception: it can't decide approvals or list the whole team's approvals. Create a key with approvals:write for that.

Missing scope

A request without the scope it needs returns 403:

{
  "error": "insufficient_scope",
  "message": "This API key does not have the crm:write scope. Create a key with it in Finn: Settings > Integrations > API keys.",
  "required_scope": "crm:write"
}

Nothing was done. Don't retry with the same key. The rate limit is counted before the scope check, so these requests still count toward it.

In the API reference, each operation names its scope in its description and in the x-required-scope field.

Sensitive fields

A workspace can mark custom fields as sensitive (passport number, medical notes). Without crm:sensitive:read, record reads replace each such value:

{ "redacted": true, "set": true, "hint": "••••4821" }
  • set says whether the field has a value.
  • hint (the last 4 characters) appears only for short ID-like values, never for free text.

Webhooks are not redacted: they go to endpoints you set up in Finn.

What a key can never do

Some actions stay with people in Finn, whatever the key's scopes:

  • Move a record past a stage check (409).
  • Decide a payment approval, or approve an edited proposal.
  • Decide approvals in bulk.
  • Change a record's owner, links or files.
  • Manage API keys or webhook endpoints.