Skip to main content

​
About

Every developer-API call runs as the key’s owning user. Two things then decide whether a call is allowed to proceed:
  1. Your scopes — is the key permitted to run this kind of operation at all?
  2. 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: 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: 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.
Not every id is a pre-checked resource idThe gateway pre-checks the ids an operation declares as resource ids — which varies by operation. A secondary id an operation doesn’t declare (for example a tag id on a contact write) isn’t a preflight 403; it’s validated by the operation as it runs and surfaces its own error (an unknown tag comes back as NOT_FOUND, not forbidden). Each area’s page notes what it guards.
Structure edits require ownershipA few operations require owned access, not just shared — editing the structure of a pipeline (renaming or reordering its stages, deleting it) is the pipeline owner’s prerogative, so those calls return 403 forbidden on a pipeline that’s merely shared with you. Reading and moving deals within a shared pipeline works normally.

​
What a 403 means

There are two distinct 403s — the code tells you which check failed: 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.

​
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.