Documentation menu

Roles & permissions

Five roles exist: APP_ADMIN (platform operator), and within each organization ORGANIZATION_ADMIN, ORGANIZATION_MANAGER, ORGANIZATION_USER, and ORGANIZATION_SUPPLIER. Every write is gated by role; a call without the required role returns 403 INSUFFICIENT_ROLE.

What each role can do

CapabilityUserManagerAdminSupplier
List / read events✓✓✓assigned events only
Create / update / delete events—✓✓—
Read carbon-source records✓✓✓assigned events
Create / update / delete carbon-source records—✓✓assigned events
Submit a record for review—✓✓✓
Review / approve records—✓✓—
Read computed results✓✓✓—
Manage users (invite, update, remove)—list/read✓—
Manage the supplier pool + assignments—✓✓—
Org configuration (categories, departments, user groups)read✓✓—
Update organization settings——✓—

The reference marks role requirements per operation — summaries note (manager+) or (admin) where a write is restricted. APP_ADMIN can do everything, in any org, by selecting the org with X-Organization-Id.

How supplier access differs

Suppliers are external collaborators, not org members: they see only events they've been assigned to and work through carbon-source records. On most record types a supplier is confined to rows they created (the row is pinned to them server-side). Exception: the activity, product and service types carry no per-row supplier pin, so suppliers are refused on them entirely with 403 SUPPLIER_NOT_PERMITTED.

Which role should an integration use?

Recommendation: Use ORGANIZATION_USER only for read-only integrations — it covers reading events, carbon-source records and results, but cannot write records. Any integration that creates, updates or submits records needs ORGANIZATION_MANAGER, which also covers creating events, managing suppliers, and review/approve. Avoid admin service accounts unless the integration genuinely manages users or org settings.