Organisations

Every call acts for one organisation, and how a token for several names it.

An organisation is never an input to an operation. It comes from the token, and nothing in a request body or query string can change it. That is what makes the API safe to hand to a third-party app or an AI assistant: the worst it can do is act within the organisations a user approved.

One organisation

A token for one organisation (an organisation's own client, or a user who approved one) needs nothing more. Every call acts for it.

Several organisations

A user who belongs to several organisations can approve an app for one, several, or all my organisations, which also covers ones they join later. Such a token must say which organisation each call is for:

REST: the Synced-Organisation header, with the organisation's id.
MCP: every tool takes a required organisation argument.

GET /v1/organisations lists the organisations a token can use, and says whether the header is required:

curl 'https://api.syncedhq.com/v1/organisations' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "organisations": [
    { "id": "a65e26c7-…", "name": "Habiqo Constructions Pty Ltd" },
    { "id": "0f27c98e-…", "name": "Streamline Advisory" }
  ],
  "allOrganisations": false,
  "organisationRequired": true
}

What is refused

Situation	Response
A multi-organisation token names none	`400` `organisation_required`
An organisation the token was not approved for	`403`
An organisation the user has since left	`403`
An organisation's own client naming another organisation	`403`

Roles

A user's connection can only call an operation their role in that organisation allows. By default every role may call a read and only admins may call something that changes data; an admin can change this per operation, and some operations follow a permission the organisation sets. Each operation's page lists its default roles. A refused call gets 403 role_not_allowed before anything is forwarded.

An operation whose results differ by user (for example bank transactions, which a submitter sees only for their own accounts) narrows them to the user the token belongs to.