Authentication

The OonoBox API authenticates with API keys. Each key belongs to one workspace and carries a fixed set of scopes.

Create a key

1. Open OonoBox → Settings → API keys.
2. Click Create key, give it a name (e.g. "Orders backend"), and select the scopes it needs.
3. Copy the key — it looks like oono_sk_live_ followed by 32 characters. It's shown only once. Store it somewhere safe (a secrets manager / environment variable), never in client-side code or version control.

If a key leaks, revoke it in the same screen and create a new one. Revocation takes effect immediately.

Send the key

Pass it as a bearer token on every request:

curl https://api.oonobox.co.zw/api/v1/contacts \
  -H "Authorization: Bearer oono_sk_live_xxxxxxxxxxxxxxxx"

Scopes

A request is allowed only if the key has the scope the endpoint requires:

Grant the least a key needs. A reporting integration that only reads contacts should get contacts.read and nothing else.

Failed authentication

A missing, malformed, revoked, or wrong-scope key all return the same response, so an attacker can't tell which check failed:

{ "error": { "code": "NOT_AUTHENTICATED", "message": "Authentication required." } }

Status code 401. See Errors for the full list.