Getting started

Three ways to call the API. Pick the one that matches your context.

1. From the web app (cookie auth)

If you're already signed in to OneBusiness, every request to /api/v1/metrics/... carries your session cookie automatically. No extra setup:

const res = await fetch("/api/v1/metrics/revenue.total/value?period=ytd", {
  credentials: "include",
});
const { data, meta } = await res.json();
console.log(data.value, meta.baseCurrency);   // 180950 "AUD"

You inherit the capabilities of your membership role on the active organisation. Owners and admins see every metric; members and contractors see the public set only.

2. From a script or partner integration (API key)

Mint a key once, then send it in the Authorization header.

Mint: Settings → API Keys → name the key → tick the capabilities you need → copy the secret. The full key is shown once — you can't recover it later.

Use:

curl -H "Authorization: Bearer one_pk_…" \
  "https://app.okavango.io/api/v1/metrics?category=cash"

{
  "data": [
    { "id": "cash.balance",         "label": "Cash balance",          "shape": "scalar",     "unit": "currency", "category": "cash" },
    { "id": "cash.in_period",       "label": "Cash in",               "shape": "scalar",     "unit": "currency", "category": "cash" },
    { "id": "cash.out_period",      "label": "Cash out",              "shape": "scalar",     "unit": "currency", "category": "cash" },
    { "id": "cash.net_flow",        "label": "Net cash flow",         "shape": "scalar",     "unit": "currency", "category": "cash" },
    { "id": "cash.on_hand_monthly", "label": "Cash on hand by month", "shape": "timeseries", "unit": "currency", "category": "cash" },
    { "id": "cash.net_flow_monthly","label": "Net cash flow by month","shape": "timeseries", "unit": "currency", "category": "cash" }
  ],
  "meta": { "total": 6, "version": 1, "computedAt": "…" }
}

API keys carry their own capability scopes, independent of the underlying user's role. A metrics.read-only key minted by an owner can read public metrics but not comp.* or paygap.*. See Authentication for the full policy.

3. Resolve a value

Pick a metric from the reference, then call /value with a period:

curl -H "Authorization: Bearer one_pk_…" \
  "https://app.okavango.io/api/v1/metrics/revenue.total/value?period=last_fy"

{
  "data": { "kind": "scalar", "value": 1851795.40, "currency": "NZD" },
  "meta": {
    "metric": "revenue.total",
    "period": {
      "requested": { "type": "relative", "period": "last_fy" },
      "resolved": {
        "startDate": "2024-04-01",
        "endDate": "2025-03-31",
        "asOfDate": "2025-03-31",
        "kind": "range",
        "label": "Last FY (FY 2024)"
      }
    },
    "asOf": null,
    "baseCurrency": "NZD",
    "computedAt": "…",
    "version": 1
  }
}

The meta.period.resolved object tells you exactly which dates the registry computed against — useful when relative periods would otherwise be opaque.

What's next

• Period syntax — mtd, ISO ranges, and the ?asOf= historical-pin parameter
• Batch reads — when a dashboard needs 10 numbers at once
• Error catalogue — what every code means and how to recover