Documentation menu

Organizations & scoping

Every request executes inside exactly one organization. Which one depends on the caller's role — and for most integrations it's determined automatically.

Org members: automatic scoping

Callers whose account belongs to an organization (admin, manager, user) are scoped to that organization on every request. They cannot access another org and cannot override the scope — an X-Organization-Id header naming a different org is rejected. Cross-org reads don't return empty lists; the record is simply 404 NOT_FOUND, as if it didn't exist.

APP_ADMIN and suppliers: explicit org selection

Two caller types can operate across organizations and therefore must say which org each request targets, via the X-Organization-Id header:

  • APP_ADMIN — platform operators.
  • Suppliers — a supplier can serve events for several customer organizations, so each request names the org whose events it is working against.
curl https://api.carbon-calculator.eventzero.io/api/v2/events \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Organization-Id: 665f1c2a9b1e4a0012ab34cd"

Omitting the header as one of these callers returns 403 ORG_CONTEXT_REQUIRED.

Ownership is server-controlled

You never write organizationId, clientId, or eventId fields yourself: they are stamped server-side from the authenticated context and silently ignored if present in a request body.

Practical consequence: A typical single-org integration needs no org handling at all — authenticate as a user in the org and every call is already scoped correctly.