Authentication

Every request to /api/v1 authenticates with a Bearer API key minted in Settings → Developers.

Authorization: Bearer tpk_LiveKey0123456789abcdefghij…

Key format

Keys look like tpk_<random> — no environment segment (there is no sandbox to distinguish). The random suffix carries the full entropy of the secret.

Tabba stores only the SHA-256 hash of the key plus a prefix and the last four characters for display. If you lose the raw secret, it cannot be recovered — revoke the key and mint a new one.

Scope

Each key is created with one of two scopes:

• read — every GET endpoint. Use for dashboards and one-way read-out sync.
• read_write — everything a read key can do plus POST, PATCH, PUT, DELETE. Use for your primary sync job.

Trying to write with a read key returns:

HTTP/1.1 403 Forbidden
{
  "error": {
    "type": "forbidden",
    "code": "INSUFFICIENT_SCOPE",
    "message": "This key does not have write access.",
    "request_id": "req_…"
  }
}

Integration binding

A key is bound to one connected Dinero integration — the account's integration is baked into the key at mint time. The API never accepts an integration_id in the URL or body: your key IS the integration. This means a compromised or misconfigured key can never write to the wrong org.

If you operate several integrations (e.g. multiple entities), mint one key per integration and route requests in your client.

Rotation

The recommended zero-downtime rotation:

1. Mint a new key alongside the current one (multiple active keys per integration are supported).
2. Deploy your integration with the new key.
3. Verify the new key's last_used_at is advancing in Settings → Developers.
4. Revoke the old key.

Revocation is immediate: the next request the revoked key makes returns 401 UNAUTHENTICATED.

What the API cannot do

Deliberately outside the API:

• Invite, deactivate, or change roles of users.
• Change account billing.
• Connect a Dinero organisation (an OAuth browser flow that stays in the UI).

These stay in the Tabba UI where an admin can perform them from a signed-in session.

Never expose the key to a browser

The credential is a server-to-server admin key. There is no CORS allowance; do not embed the key in a frontend bundle or send it from a customer's browser. Every call is audit-logged with the key id and a request_id.