API notes

How the Darbase API behaves

Darbase has no public API and no API keys yet. This page describes the rules that the API behind the Darbase apps follows today.

Looking for how to use the product? The help centre is over here

Authentication: Bearer JWT, issued per tenant. Tokens carry an audience, and the broker, platform-admin and agency-portal audiences are separate — a token minted for one is rejected by the others rather than being partially honoured.
Response envelope: Every successful response is { success: true, data: T }. Errors are standard HTTP status codes with a message, never a 200 carrying an error object. If you are writing a client, branch on the status and then read data.
Pagination: List endpoints take take and skip, and cap take at 100. There is no unbounded list endpoint anywhere in the API, deliberately — a tenant with 40,000 contacts should not be able to ask for all of them in one request.
Errors: 400 for a malformed request, 401 for a missing or expired token, 403 when the token is valid but the audience or role is wrong, 404 when the resource exists for somebody else's tenant as well as when it does not exist at all. That last one is deliberate: a 404 rather than a 403 avoids confirming that a record exists in another tenant.
Webhooks: Darbase sends no outbound webhooks yet, so there is nothing to subscribe to.
Rate limits: Limits apply per IP address: 100 requests in 60 seconds. Auth endpoints allow 10 requests in 60 seconds, and an account locks after 5 failed sign-ins. A 429 response carries a Retry-After header. Wait that long before you send the request again.