Get started

Authentication

Every request is authenticated with a secret API key sent as a Bearer token. Keys carry scopes that limit what they can read and change.

API keys

Owners and admins create keys in Settings → Developers → API keys. A key looks like rbk_ followed by 43 random characters. Rabbitblaze stores only a hash: the full key is shown once, when you create it, so copy it into your secret manager right away. The dashboard identifies keys by their first characters and shows when each was last used.

Give every integration its own key with only the scopes it needs — revoking one then never breaks the others. A workspace can have up to 50 active keys.

Sending the key

Send the key in the Authorization header of every request, over HTTPS:

Request

GET /v1/contacts?limit=10 HTTP/1.1Host: api.rabbitblaze.comAuthorization: Bearer rbk_9fK2xQ1a…

Scopes

Each key has a set of scopes, chosen when you create it and editable later. A request that needs a scope the key lacks answers 403 forbidden. In the dashboard, Full access grants every scope and Read-only every :read scope.

Scope	Allows
`contacts:read`	Read people
`contacts:write`	Create, update, merge and delete people
`companies:read`	Read companies
`companies:write`	Create, update and delete companies
`conversations:read`	Read conversations and their parts
`conversations:write`	Create, reply to, assign, close, snooze and tag conversations
`tickets:read`	Read tickets and ticket types
`tickets:write`	Create and update tickets
`tags:read`	Read tags
`tags:write`	Create, rename and delete tags
`events:read`	Read tracked events
`events:write`	Track events
`articles:read`	Read articles and collections
`articles:write`	Create, publish and delete articles and collections
`teams:read`	Read teams and teammates
`data_attributes:read`	Read data attributes
`data_attributes:write`	Create and update data attributes
`segments:read`	Read segments

Scopes come in pairs per resource (people, companies, conversations, tickets, tags, events, help center, teams, data attributes, segments); teams:read and segments:read have no write counterpart. Write scopes don’t include read: a key that only tracks events needs nothing but events:write. Each endpoint in the reference names the scope it needs.

Acting as a teammate

Keys belong to the workspace, not to a person. Endpoints that change a conversation accept an optional teammateId: the change is then shown in the timeline and in reports as made by that teammate. Without it, it’s shown as made by Rabbitblaze. Replies sent as a teammate and internal notes always need one. Deletions and merges made with a key are recorded in the workspace’s audit log with the key’s name.

Authentication errors

Status	Code	When
401	`unauthenticated`	No key, an unknown key or a revoked key.
403	`forbidden`	The key lacks the endpoint’s scope.
403	`plan_limit`	The workspace’s plan doesn’t include the REST API (Free).

401 Unauthorized

{  "error": {    "code": "unauthenticated",    "message": "Invalid or revoked API key"  }}

403 Forbidden · missing scope

{  "error": {    "code": "forbidden",    "message": "This API key is missing the \"contacts:write\" scope"  }}

403 Forbidden · plan

{  "error": {    "plan": "free",    "feature": "api",    "code": "plan_limit",    "message": "Upgrade your plan to use this feature"  }}

Rotating keys

Create a new key with the same scopes.
Deploy it to your integration and check that requests succeed (GET /v1/me).
Revoke the old key in Settings → Developers → API keys. Requests with it fail right away.