Scopes — Finn docs

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

Scope	Allows	Endpoints
`voice`	Voice agents and calling	Every endpoint tagged Calls, Finns, Voices, Phone numbers, Audiences, Deployments, Wallet, and listing and adding do-not-call numbers
`dnc:write`	Take a number off the do-not-call list, so Finn may call it again	`DELETE /do_not_call/{phone}`
`crm:read`	Read records, kinds, fields and timelines	`GET /record_kinds`, `GET /fields`, `GET /contacts`, `GET /contacts/{id}`, `GET /contacts/{id}/timeline`
`crm:sensitive:read`	See the values of fields marked sensitive	Same reads; without it those values are hidden
`crm:write`	Create and update records, add notes	`POST /contacts`, `PATCH /contacts/{id}`, `POST /contacts/{id}/notes`
`cases:read`	Read Finn Operator cases and approvals	`GET /cases`, `GET /cases/{id}`, `GET /cases/{id}/events`, `GET /approvals`, `GET /approvals/{id}`
`cases:write`	Start a case	`POST /agents/{id}/cases`
`approvals:write`	Decide an approval	`POST /approvals/{id}/decide`, `/approve`, `/reject`
`chat:read`	Read the chat inbox through the Chat API	`GET /channels`, `GET /conversations`, `GET /conversations/{id}`, `GET /conversations/{id}/messages`, `GET /contacts`, `GET /contacts/{id}` on `https://chat.hirefinn.ai/finn-api/public/v1`
`chat:write`	Send WhatsApp, SMS and email, start conversations, edit chat contacts	`POST /conversations`, `POST /conversations/{id}/messages`, `PATCH /contacts/{id}` on the Chat API

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.
chat:write includes chat:read.
dnc:write includes voice.

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 two exceptions: it can't decide approvals or list the whole team's approvals, and it can't remove do-not-call numbers. Create a key with approvals:write or dnc:write for those. It also keeps full access to the Chat API.
approvals:write decides approvals only when your organization has turned on approval decisions by API key. It is off by default; ask Finn support. Until then decisions return 403 approvals_by_api_off.

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.