Get started

Scopes

A scope is a permission you give an API key or an app. Give each key only the scopes it needs.

How scopes work

A key's scopes are fixed when it is created. To change them, create a new key and revoke the old one.
Write includes read. leads:write also allows everything leads:read does. The same holds for :manage (includes :read and :write) and ai:use (includes ai:read). messages:send includes messages:read, and automations:run includes automations:read.
Missing scope. An action the key's scopes do not allow answers 403 forbidden with permission naming what was checked (for example leads.edit), or missing_scope with scope naming the scope to add. Some lists filter instead of refusing: conversations and tasks the key may not see are left out, so the list comes back empty. A single record the key may not see answers 404, so ids never leak.
Full data. A key that can read contacts sees their phone numbers and emails in full. People in Kweko may see them masked, depending on their role; that masking does not apply to keys.
Apps request scopes from the same list, plus ui:extend to add UI to Kweko. See OAuth for apps.

All scopes

Generated from the list the API accepts (GET /v1/api-keys/scopes returns the same list to owners and admins). "Reserved" scopes are accepted but no endpoint checks them yet.

Scope	What it allows
`leads:read`	List and read leads (`GET /v1/leads`, the board), list pipelines and stages, and read the timeline of a lead.
`leads:write`	Create, change, delete and restore leads, and manage a lead's contacts and products. Includes `leads:read`. Imports and exports of leads also check it.
`contacts:read`	List and read contacts (with full phone numbers and emails) and read a contact's timeline.
`contacts:write`	Create, change, delete and restore contacts. Includes `contacts:read`.
`companies:read`	List and read companies and read a company's timeline.
`companies:write`	Create, change, delete and restore companies. Includes `companies:read`.
`pipelines:read`	Reserved: no endpoint checks it yet. Listing pipelines needs `leads:read`.
`pipelines:manage`	Create, change and delete pipelines and their stages.
`fields:read`	Reserved: listing custom fields (`GET /v1/fields`) needs no scope.
`fields:manage`	Create, change and delete custom fields.
`timeline:read`	Reserved: the timeline of a record needs the read scope of that record type (`leads:read`, `contacts:read` or `companies:read`).
`notes:write`	Add notes to leads, contacts and companies, and pin or unpin them.
`messages:read`	List and read conversations and their messages. Messages contain personal data, so the read-only preset leaves this scope out.
`messages:send`	Send messages in conversations and retry failed ones. Includes `messages:read`.
`conversations:manage`	Assign, resolve, reopen and snooze conversations.
`tasks:read`	List and read tasks.
`tasks:write`	Create, change, complete, reopen, snooze and delete tasks. Includes `tasks:read`.
`products:read`	List and read the product catalog.
`products:write`	Create, change and archive products. Includes `products:read`.
`calls:read`	List calls.
`calls:write`	Record call outcomes and download recordings. Includes `calls:read`.
`files:read`	Reserved: v1 has no file endpoints yet.
`files:write`	Reserved: v1 has no file endpoints yet.
`tags:manage`	Rename, recolor, merge and delete workspace tags and change the tag settings. Tags are set on records through the record's own write scope.
`users:read`	List the workspace's members (`GET /v1/members`): names, emails and roles.
`automations:read`	List and read automations and their runs.
`automations:run`	Start automations that have the manual trigger. Includes `automations:read`.
`automations:manage`	Create, change, enable, disable and delete automations.
`variables:read`	Reserved: no endpoint checks it yet.
`variables:write`	Reserved: no endpoint checks it yet.
`audit:read`	Read the workspace audit log.
`webhooks:manage`	Create, change, test and delete webhooks, rotate their secrets and replay deliveries.
`reports:read`	Read analytics: metrics, dashboards and drill-downs.
`import:write`	Import leads, contacts or companies from a file. Needs the record type's write scope too (for example `leads:write`).
`export:read`	Bulk export to a file. Sensitive: not in the read-only preset. Needs the record type's read scope too (for example `contacts:read`).
`workspace:read`	Read the workspace's usage and plan limits (`GET /v1/usage`).
`ai:read`	Reserved: no endpoint checks it yet.
`ai:use`	Use Kweko AI features (summaries, drafts, translation) when the workspace has turned AI on.

Scopes per endpoint

The API reference shows the scope next to each endpoint.