Overview & quickstart

One API across every module. Every request is scoped to the tenant that owns the key, every webhook is signed, and every error returns a safe message with an incident ID — never internals.

What you can build

Quickstart in three steps

1. Use the sandbox key. It reads a fictional tenant (Kusasa Facilities, sample) and can write evidence and leads. It cannot provision tenants — that returns 403 by design.

   bo_test_SandboxDemoKey0000000000Ab

2. Make your first call.

   curl https://blueoceansapproach.co.za/api/v1/deliverables?status=submitted \
     -H "Authorization: Bearer bo_test_SandboxDemoKey0000000000Ab"

3. Subscribe to webhooks and verify the BO-Signature header — see Webhooks & signatures.

Node.js (no SDK required)

const res = await fetch("https://blueoceansapproach.co.za/api/v1/kpis?workerId=w-07", {
  headers: { Authorization: `Bearer ${process.env.BO_API_KEY}` },
});
if (!res.ok) throw new Error(`API error ${res.status}`); // body has { error, incident }
const { data, meta } = await res.json();
console.log(meta.weightedScore, data.length);

Writes are idempotent

Any request that creates something requires an Idempotency-Key header. Replaying the same key and body returns the original response (with Idempotent-Replayed: true); the same key with a different body returns 409.

curl -X POST https://blueoceansapproach.co.za/api/v1/deliverables/DLV-1043/evidence \
  -H "Authorization: Bearer bo_test_SandboxDemoKey0000000000Ab" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filename":"stock-count.pdf","sha256":"<64 hex>","size":182044,"mime":"application/pdf"}'

Base URL, environments and limits

Scopes

Keys carry scopes such as read:workers, read:deliverables, read:kpis, read:compliance, write:evidence, write:leads and tenant:provision (partners and administrators only). Grant the least you need.