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 / write 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 any supplier assigned to the event can read and write all rows of those types.

Which role should an integration use?

Recommendation: Start with ORGANIZATION_USER — it covers reading events, writing carbon-source records, submitting them, and reading results. Move to ORGANIZATION_MANAGER only if the integration must create events, manage suppliers, or drive review/approve. Avoid admin service accounts unless the integration genuinely manages users or org settings.