Developer Documentation

Integrate Carbon Zero with your systems — a REST API for every ESG reporting operation, API-key authentication with least-privilege grants, and signed webhooks for real-time events. This guide is written for developers building on a tenant workspace: ingesting metric submissions, streaming vessel fuel telemetry, computing Scope 1–3 emissions, and publishing disclosures.

1. Overview & architecture

Carbon Zero is a multi-tenant ESG reporting & compliance platform. It exposes a JSON REST API under /api/v1. Requests are authenticated with either a user JWT (from login) or a workspace API key, and authorized against the caller's role/grant permissions. Real-time notifications — entity, submission, disclosure, score and ticket events — are delivered out-of-band via signed webhooks.

2. Base URL & conventions

Common status codes: 200/201 success, 400 validation/business error, 401 missing/invalid credentials, 403 insufficient permission, 404 not found, 422 request schema validation. New workspaces default to AED currency, Asia/Dubai timezone and dd/mm/yyyy date format (editable in Settings).

3. Authentication

User JWT

Logging in returns a bearer token for that user, scoped to their workspace and role.

# Login → JWT
curl -X POST https://<domain>/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@org.com","password":"••••••"}'

# → { "access_token": "eyJ…", "token_type": "bearer", "user": {…}, "tenant": {…} }
curl https://<domain>/api/v1/auth/me -H "Authorization: Bearer eyJ…"

A user can update their own profile with PATCH /api/v1/auth/me/preferences (e.g. {"date_format":"mm/dd/yyyy"}) and change their password via POST /api/v1/auth/me/change-password; the workspace defaults (currency, timezone, date_format) are set via PATCH /api/v1/tenants/settings.

The same login also sets the session as HTTP-only cookies (used by the Carbon Zero web app, so the token is never exposed to JavaScript) — an httpOnly cz_access cookie, a JS-readable cz_csrf cookie, and a rotating cz_refresh. The body access_token is retained for programmatic callers. Cookie-authenticated, state-changing requests must echo the readable cz_csrf value in an X-CSRF-Token header (double-submit CSRF); access cookies are renewed via POST /auth/refresh and cleared by POST /auth/logout. A main.py middleware bridges the cookie → Authorization: Bearer for every token-decode dependency. For integrations, prefer an API key (below) — it needs no cookies, CSRF, or refresh handling.

API keys (recommended for integrations)

An API key is a standalone principal — it authenticates as itself, not the user who created it, so it survives that user leaving. Mint keys under Developer → API Keys. When minting a key you pick a name, optional expiry, and exactly which (resource, action) grants it should hold.

• The secret looks like cz_live_… and is shown exactly once at creation — store it securely. Only a hash is kept server-side.
• A key's grants are validated against the creator's own permissions at creation — a key can never exceed its creator (least privilege).
• Pass it as X-API-Key: cz_live_… or Authorization: Bearer cz_live_… (the cz_live_ prefix disambiguates from a JWT).
• Revocation is immediate; expires_at is enforced; an API-key principal can call business endpoints but cannot mint other keys.

# Same request, with an API key
curl https://<domain>/api/v1/reporting-entities \
  -H "X-API-Key: cz_live_xxxxxxxxxxxxxxxx"

The RBAC model

Every gated endpoint requires a (resource, action) permission. has_permission is exact-match (no wildcards). Roles grant permissions; API keys carry a subset of grants. The owner role's grants are seeded at tenant creation. Resources:

4. Quickstart

Mint a key with submissions grants in the dashboard, then create a reporting entity and upsert a metric submission:

# 1. Create a reporting entity (organization / subsidiary / facility / supplier / vessel)
curl -X POST https://<domain>/api/v1/reporting-entities \
  -H "X-API-Key: cz_live_…" -H "Content-Type: application/json" \
  -d '{"name":"MV Gulf Pioneer","entity_type":"vessel","identifier":"9876543"}'

# 2. Upsert a metric submission (unique per period × entity × metric)
curl -X POST https://<domain>/api/v1/submissions \
  -H "X-API-Key: cz_live_…" -H "Content-Type: application/json" \
  -d '{"entity_id":"<entity-uuid>","period_id":"<period-uuid>","metric_id":"<metric-uuid>","value":"1250.5"}'

5. API reference

All paths are relative to /api/v1. Browse full request/response schemas in the live /api/docs explorer (access-restricted) or the API Explorer tab. Highlights by domain:

Reporting entities

A reporting entity is the subject of ESG data — an organization, subsidiary, facility, supplier or vessel — with a parent_id hierarchy and custom-field values. Entities are owner + branch scoped (a caller sees only their accessible_entity_ids unless they hold reporting_entities:view_all). Vessels carry their IMO number as identifier and are the subject of the fuel-feed Scope 1 evidence layer.

Frameworks & metric catalogue

A framework (GRI, SASB, CSRD-ESRS, TCFD, GHG-Protocol, plus the seeded UAE & maritime standards) defines a catalogue of metrics — each with a pillar (E/S/G), a value_type and a unit. Frameworks move draft → active; metrics belong to a framework.

Reporting periods

A reporting period (campaign, e.g. FY2025) is a collection cycle. Submissions and scores are keyed by period. A period is open or closed.

Metric submissions

The metric-submission ledger is the heart of data collection: one value per (period × entity × metric), with evidence and a status. POST is an upsert — there is a unique triple, so re-posting the same combination updates in place rather than creating a duplicate. The lifecycle is draft → submitted → verified → rejected, advanced with the review endpoint.

Disclosures

A disclosure (ESG report) is produced per (entity × framework × period) and moves draft → in_review → approved → published. On publish the disclosure takes an immutable snapshot of its metric values, plus a transition history — so a published report never drifts as later submissions change.

ESG scoring

A scoring model holds weighted criteria. Each criterion is either a numeric set of bands or a simpleeval expression over a metrics context. The weighted average of criterion scores yields a 0–100 score, mapped to a tier from the model's tiers. An EsgScore is upserted per (model × entity × period) with a per-criterion breakdown.

Targets

A target sets a per-(entity × metric) baseline → target goal. Progress is direction-aware (reduction vs increase) and computed live as a progress_pct from the latest submission for that metric.

Emissions (Scope 1–3 calculator)

The emissions module computes activity-based (primary) and spend-based (fallback) emissions, each split into WTT + TTW → total tCO2e. An EmissionFactor catalogue (kgCO2e/unit, WTT+TTW) is lazy-seeded on first use with maritime fuels (HFO / VLSFO / MGO / LNG / methanol / biofuel / ammonia, per tonne), transport modes (per tonne-km), and spend categories (per currency). An ActivityRecord computes from a fuel burn / tonne-km amount (activity-based) or a spend amount (spend-based); the summary rolls results up by Scope 3 category + method. Gated on the submissions resource (no new RBAC).

Vessel fuel feeds (Scope 1 evidence)

For maritime Scope 1, accuracy lives in the fuel-mass figure (the IMO emission factor is fixed), so this layer ingests granular fuel observations per vessel and builds an auditable, reconciled trail before it ever reaches the emissions summary.

Each FuelConsumptionRecord carries a source that maps to an IMO DCS / EU-MRV method and a data-quality tag:

Ingest is idempotent on the unique tuple tenant + entity + source + source_ref — re-posting the same observation updates it in place, so at-least-once / retried delivery from shore-side systems is safe. Each record computes its TTW (Scope 1) and WTT (Scope 3 cat 3) via the shared emissions_service. The Bunker Delivery Note is the auditable "fuel uplifted" anchor; reconcile compares Σ feed vs Σ BDN per (vessel × period), computes per-fuel variance %, flags anything beyond the 5% tolerance, and marks reconciled records. rollup then collapses the reconciled feed into one emissions.ActivityRecord per (vessel × period × fuel) (idempotent — refreshes in place), so the existing summary / scoring / disclosure pipeline consumes it unchanged. Gated on the submissions resource; the cz_live_ API-key path is the intended channel for machine ingestion.

# Shore-side machine ingest of a noon report (idempotent on source_ref)
curl -X POST https://<domain>/api/v1/emissions/fuel-feed \
  -H "X-API-Key: cz_live_…" -H "Content-Type: application/json" \
  -d '{"records":[{"entity_id":"<vessel-uuid>","source":"noon_report","source_ref":"NR-2025-04-12","fuel_type":"VLSFO","quantity_tonnes":42.7,"period_id":"<period-uuid>"}]}'

Customer care (entity-360) & support tickets

The customer-care module is an entity-360 view — search any entity and pull a consolidated overview (submissions, disclosures, scores, targets, tickets, notes). It is gated on customer_care:access and deliberately ignores owner/branch scoping. Support tickets are entity-linked, numbered TKT-{year}-{n}, with a comment thread and status / priority / assignee.

Report builder & automation

The report builder is a compose-over-catalogue engine: pick a source (entities / submissions / disclosures / scores / targets), choose whitelisted fields, run, and optionally save the definition or export CSV. Automation is an event-driven rules engine — a rule's trigger is a webhook event, with an optional simpleeval condition over the payload and an action of create_ticket | add_note | emit_event; runs are logged as a ProcessRun and fired alongside the webhook emit.

Dashboard, workspace & settings

The dashboard summary is branch∩owner-scoped analytics; the rest are workspace administration — settings, roles & members, invitations, branches, maker-checker dual control, reference data, custom fields, webhooks and billing.

Platform admin (cross-tenant)

The platform admin console is a cross-tenant operator surface under /admin, gated by the is_platform_admin flag via require_platform_admin — separate from per-tenant RBAC. It exposes cross-tenant stats, tenant management, owner impersonation, an editable plan catalogue and a read-only SQL console.

6. Webhooks

Register HTTPS endpoints to be notified when events occur (e.g. a disclosure is published). Configure them under Developer → Webhooks (or POST /webhooks): a URL, the events to subscribe to, and a signing secret (whsec_…) shown once.

Delivery flow

The request & envelope

Each delivery is an HTTP POST with these headers and a stable envelope:

{
  "event": "disclosure.published",
  "event_id": "3f12e818-55b8-440c-95ee-f6bdcf31b25e",
  "occurred_at": "2026-06-06T03:57:16.011200+00:00",
  "tenant_id": "2eef904a-af99-44a4-9a5e-30628b0eb2bc",
  "data": { /* event-specific */ }
}

Verifying signatures

Always verify before trusting a payload.

Python (FastAPI)

import hmac, hashlib, json

def verify(raw_body: bytes, sig: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig or "")

@app.post("/webhooks/carbonzero")
async def receive(request: Request):
    raw = await request.body()              # raw bytes, not request.json()
    if not verify(raw, request.headers.get("X-CarbonZero-Signature"), SECRET):
        raise HTTPException(401, "bad signature")
    event = json.loads(raw)
    # dedupe on event["event_id"], then process async, return 2xx fast

Node (Express)

const crypto = require('crypto')
// capture raw body: app.use(express.raw({ type: 'application/json' }))
function verify(rawBody, sigHeader, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(expected), b = Buffer.from(sigHeader || '')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

app.post('/webhooks/carbonzero', (req, res) => {
  if (!verify(req.body, req.get('X-CarbonZero-Signature'), SECRET))
    return res.sendStatus(401)
  const evt = JSON.parse(req.body.toString())
  // dedupe on evt.event_id, ack fast (2xx), process async
  res.sendStatus(200)
})

Delivery semantics

• Respond 2xx quickly. Non-2xx / timeout / connection error = failure.
• Retries with backoff, then dead (manually retryable via the dashboard or /{id}/deliveries/{delivery_id}/retry). The delivery id is stable across retries.
• At-least-once → be idempotent. Deduplicate on event_id.
• No ordering guarantee. Use occurred_at if you need order.
• HTTPS only, publicly reachable (private/internal addresses are rejected).

Event types

Webhook endpoints are managed under /webhooks — GET /webhooks/event-types lists the catalogue above, CRUD on /webhooks registers endpoints, POST /webhooks/{id}/roll-secret rotates the whsec_ secret, GET /webhooks/{id}/deliveries inspects history, POST /webhooks/{id}/deliveries/{delivery_id}/retry replays a dead delivery, and POST /webhooks/{id}/test fires a test event.

7. End-to-end integration example

A typical server-to-server ESG reporting flow, combining the API with a webhook receiver:

1. Create the reporting entity — POST /reporting-entities (org / subsidiary / facility / supplier / vessel).
2. Define the framework + metrics — POST /frameworks, then POST /frameworks/{id}/metrics for each data point; publish the framework to active.
3. Open a period — POST /periods (e.g. FY2025).
4. Upsert submissions — POST /submissions per (period, entity, metric); re-posting updates in place.
5. Verify — POST /submissions/{id}/review; listen for submission.verified.
6. Run scoring — POST /scoring/run → an EsgScore (0–100 → tier); listen for score.computed.
7. Publish a disclosure — POST /disclosures then POST /disclosures/{id}/transition through to published; act on disclosure.published (the snapshot is now immutable).

Maritime: vessel fuel feed → reconcile → roll-up

For Scope 1 fuel evidence on vessels, a second short flow feeds the same emissions pipeline:

1. Ingest fuel observations — POST /emissions/fuel-feed (idempotent on tenant+entity+source+source_ref); each computes TTW + WTT.
2. Record BDNs — POST /emissions/fuel-feed/bdn as the auditable "fuel uplifted" anchor.
3. Reconcile — POST /emissions/fuel-feed/reconcile compares Σ feed vs Σ BDN per vessel × period, flags variance beyond 5%.
4. Roll up — POST /emissions/fuel-feed/rollup collapses the reconciled feed into one ActivityRecord per vessel × period × fuel — it then appears in GET /emissions/summary and flows into scoring & disclosures unchanged.

8. Reference appendix

Idempotency & safety

• Webhook deliveries are at-least-once; dedupe on event_id.
• Metric submissions are an upsert on the unique (period × entity × metric) triple — a re-post updates in place, never duplicates.
• Vessel fuel-feed ingest is idempotent on tenant + entity + source + source_ref; the roll-up refreshes its ActivityRecord in place — safe for at-least-once delivery.
• A disclosure's published snapshot is immutable — later submission changes never alter a published report.
• Treat webhook data as forward-compatible — ignore unknown fields rather than rejecting.

Versioning & limits

• The API is versioned in the path (/api/v1).
• Design for least-privilege keys and rotate manually by minting a new key and revoking the old.
• Emissions are reported in tCO2e with a WTT / TTW split; money is per-currency (workspace default AED) and never summed across currencies.

Quick error reference