Scopes
Every permission an API key or application can hold.
A scope is one permission, written resource:action. A credential holds a set of them, and every
request checks the scope the endpoint declares.
Holding a scope is necessary but not sufficient: your role is checked too, live, on every request. See Authentication.
This page lists the catalogue as it exists in the product. You can also fetch it as JSON from
GET /api/v1/scopes and render it yourself, which is what the dashboard's permission picker does.
Wildcards
Two shorthands are accepted when you create a credential:
| Wildcard | Expands to |
|---|---|
*:read | every standard read scope |
* | every standard scope, read and write |
Wildcards expand to standard scopes only. They never include a sensitive or privileged scope — so asking for "everything" does not quietly hand out the audit log, billing, or candidate email bodies. Those must be named individually.
Selecting a write scope also grants its read half, where one exists. There is no way to hold
jobs:write without jobs:read.
Standard
Included by * and, for the read halves, by *:read.
| Scope | Grants |
|---|---|
apps:read | List installed applications and API keys. |
jobs:read | Jobs, requisitions, and stage configuration. |
jobs:write | Create and edit jobs and stages. |
candidates:read | Profiles, applications, and stage history. |
candidates:write | Move stages, edit profiles, add notes. |
companies:read | Company records in your CRM. |
companies:write | Create and edit company records. |
interviews:read | Scheduled interviews, stages, and debriefs. |
interviews:write | Manage interview stages and scorecards. |
scheduling:read | Availability and bookings. |
insights:read | Agent learnings and insight tags. |
insights:write | Create, archive, and theme insights. |
pipeline:read | Stage counts, throughput, and stalled work. |
onboarding:read | Onboarding state for the active client. |
agents:read | List sessions and available agents. |
organization:read | Organization profile and settings. |
members:read | Who is in the organization and their roles. |
Sensitive
Never included by a wildcard. Name them explicitly.
| Scope | Grants | Minimum role |
|---|---|---|
candidate_emails:read | Inbound and outbound message bodies, including personal data. | org:member |
candidate_emails:write | Send mail to a candidate. | org:member |
scheduling:write | Books and cancels real calendar events with real people. | org:member |
agents:history | Full transcripts, which carry candidate and client detail. | org:member |
agents:invoke | Runs the agent, which can reach every other scope this credential holds. | org:member |
agents:write | Create, rename, and cancel sessions. | org:member |
clients_messaging:write | Sends an outbound message to a client. | org:member |
billing:read | Subscription status, agreements, and invoice summaries. | org:admin |
audit:read | The organization's audit trail. | org:admin |
agents:invoke runs the agent, and the agent can reach every other scope the same credential
holds. Granting it is closer to granting the whole credential than to granting one endpoint.
Always granted
| Scope | Grants |
|---|---|
context:read | Discover what this workspace exposes. |
Privileged — not grantable
These exist in the vocabulary so that the dashboard and the audit trail can name them, but no credential can hold one. They are refused even when requested explicitly, so a request naming one does not half-succeed.
| Scope | Grants |
|---|---|
apps:write | Create and revoke credentials. |
organization:write | Rename the organization and change settings. |
members:write | Invite, remove, and change roles. |
billing:write | Change what the organization pays. |
Anything in this table is done by a person in the dashboard, never by a key or an application.
Last updated on