Authorization
How the developer API decides what a key may do — scopes, organization access, and what a 403 means
About
Every developer-API call runs as the key’s owning user. Two things then decide whether a call is allowed to proceed:
- Your scopes — is the key permitted to run this kind of operation at all?
- Your organization’s access — does your org own (or have shared access to) the specific records the call references?
If either check fails, the request stops with a 403 before any data is read
or written. You never get back a record your organization can’t see.
Request checks
Under the hood, an authorized call passes these checks in order. They map to the two questions above plus the always-on identity and visibility guarantees:
| Check | Question | Failure |
|---|---|---|
| Authentication | Is the bearer key valid and un-revoked? | 401 unauthorized |
| Scope | Does the key carry the scope this operation requires? | 403 insufficient_scope |
| Subscription | Does your organization have a usable plan for data operations? Billing and profile recovery reads remain available. | 402 subscription_inactive (repeated refusals can become 429 rate_limited) |
| Organization access | Does your org own or share every record id the call references? | 403 forbidden |
| Visibility | Runs as you — you only ever see the rows and fields you’d see in the app. | (no error — filtered) |
Authentication, scopes, and subscription access are covered in the Overview. This page is about organization access, which is what keeps one org’s data invisible and untouchable to another.
Organization access
Each operation declares which of its variables are resource ids — the
dealId, contactId, pipelineId, or destination stageId it acts on. Those
are checked against your organization before the operation runs, at one of two
levels:
| Level | Meaning |
|---|---|
| Owned | The record belongs to your organization. |
| Shared | The record belongs to another org but is reachable by yours — for example a deal in a pipeline shared with you through a partnership. |
Most operations accept owned or shared access. A call that references an id
your org can neither own nor reach returns 403 forbidden. The same response
also covers missing or deleted guarded records; it does not reveal which case
applies. Where an operation guards a list of ids (for example the userIds
and contactIds on
createDeal / updateDeal), one foreign id fails the whole call rather than
being partially applied.
What a 403 means
There are two distinct 403s — the code tells you which check failed:
| Code | Cause | Fix |
|---|---|---|
insufficient_scope |
The key lacks the scope the operation requires (e.g. a READ-only key calling a WRITE op, or a non-admin key calling an ADMIN op). |
Recreate the key with the needed scope. ADMIN requires the owner to be a team admin. |
forbidden |
A guarded record is missing, deleted, or outside your organization’s access. | Re-read the ids from a current list/search response and confirm your access. A 403 alone does not establish that the record exists in another org. |
A guarded id with a malformed UUID spelling or a value shape that cannot be
an id returns 400 bad_request. Values that could name a record still undergo
the access check; an empty guarded id list can be refused with 403.
Send consent attestation
Operations that message a contact run over the API only after an org admin
makes the organization’s send consent attestation: a one-time statement
that every contact the organization messages through the API consented to be
contacted. Until then each of them returns 403 send_consent_not_attested.
| operationId | Page |
|---|---|
sendText, sendEmail |
Communications |
sendContract, remindContract, completeContract, correctContract |
Contracts |
acceptContactSuggestion, acceptEditedContactSuggestion, decideSuggestion, decideContactSuggestionsInBulk |
Contacts — accepting a card can send a reply |
decideCatchUpCard |
Notifications — accepting a Catch up card can send a reply |
getSendConsentAttestation (READ) reads whether it stands (attested,
attestedAt, attestedByUserId); setSendConsentAttestation (ADMIN)
attests (true) or withdraws (false) it. Both are on the
Communications API.
Operations that spend
Operations that spend credits or money are listed, with what each spends, on the Billing API page, and flagged on their own pages.
Where this applies today
Each area’s page describes its guarded ids, including Deals, Contacts, Workflows, and Forms. Deal writes also guard forwarded stage, user, and contact ids. Organization-scoped reads derive the organization from your key instead of accepting a cross-organization id. Identity and scope checks apply to every operation.