ECO Platform integration

Everything the ECO Platform engineering team needs to connect end to end with ECO Bridge. No person-level data crosses this boundary — payloads containing PII are rejected.

Live connection test

Checks the shared signing secret, the inbound push receiver (with a real signed test envelope) and an outbound call to the platform partner API.

Recent inbound attempts

Every call the ECO Platform makes to Bridge, with the exact reason it was accepted or rejected. Field names only — no values, no payloads, no personal data.

No inbound calls recorded yet. As soon as the platform posts to Bridge, each attempt appears here.

Confirm both sides hold the same secret

Run the test above and read the fingerprint line. Then run this on the ECO Platform side with your copy of the shared secret. Identical values mean the secrets match — the fingerprint reveals nothing about the secret itself.

printf '%s' 'eco-bridge-secret-check/v1' | openssl dgst -sha256 -hmac "$ECO_SHARED_SECRET" | awk '{print substr($2,1,16)}'

Base URL & signing

—

Every inbound POST is authenticated with a shared secret held by both sides. Sign the exact raw request body and send the hex digest in a header:

x-eco-signature: hex(HMAC-SHA256(rawBody, ECO_WEBHOOK_SECRET))

The secret itself is never displayed here or transmitted. Bridge answers 401 on a signature mismatch, 404 for an unknown organisation ECO ID, 422 when the PII guard suppresses a payload and 503 if the secret is not installed.

Endpoints the platform calls on Bridge

POST

/api/public/eco-events

Push newly verified or attributed events to Bridge in real time.

{
  "orgEcoId": "eco:org:01H...",
  "events": [
    {
      "event_id": "evt_123",
      "event_type": "event.verified",
      "domain": "waste",
      "occurred_at": "2026-09-08T10:00:00Z",
      "quantity_kg": 120,
      "estimated_value_ngn": 48000
    }
  ]
}

POST

/api/public/orgs/provisioned

Tell Bridge an organisation has paid and been provisioned on the platform.

{
  "ecoOrgId": "eco:org:01H...",
  "name": "Acme Foods Ltd",
  "contactEmail": "ops@acme.com",
  "plan": "growth",
  "consentGrantId": "grant_123"
}

// Only ecoOrgId and name are required. snake_case is accepted everywhere,
// and these spellings all work:
//   ecoOrgId | eco_org_id | orgEcoId | ecoId
//   name     | org_name   | businessName
//   plan     | plan_id    | tier
// Anything rejected comes back with the exact reason and the keys we received.

POST

/api/public/handoff/verify

Validate a signed handoff token when sending a partner from the platform into Bridge.

{ "token": "<signed handoff token>" }

GET

/api/public/certificates/:certificateId

Check whether a CSR certificate issued by Bridge is still valid.

Endpoints Bridge calls on the platform

Sent with Authorization: Bearer <partner key> and x-eco-partner: eco-bridge. Each must return JSON; an HTML shell is treated as “not live yet”.

federation-service?path=pingConnection check: key, scopes and org_ref
federation-service?path=activity_syncConsent-scoped verified events for one organisation
federation-service?path=aggregateAggregated, k-anonymised event totals
federation-service?path=platform-statsPublic platform-wide statistics
federation-service?path=identity/resolveResolve an ECO ID (needs eco_id_hash)
federation-service?path=membersOrganisation members (plus /members/invite, /members/update)
federation-service?path=pools/sponsorNotify ECO of a fund-pool sponsorship
federation-service?path=billingPlan, invoices and usage
federation-service?path=gigsData gigs (plus /gigs/submissions, /gigs/fund, /gigs/review)