Carbon

Data API

Authentication

Carbon authenticates Data API requests with a scoped, optionally expiring API key — the same key that unlocks the Carbon API.

Create a key in Settings → API Keys, then send it on every request as a bearer token: Authorization: Bearer <api-key>.

Example request
curl '<your-host>/item?limit=1' \
  -H "Authorization: Bearer <api-key>"

That's the hosted Data API at rest.carbon.ms, which takes the key as a bearer token and forwards it as the carbon-key header internally. If you run Carbon yourself and call PostgREST directly, send carbon-key: crbn_… against /rest/v1/<table> instead.

Creating a key

Choosing New API Key opens a dialog with three fields:

Field
Description
Required
Name
A label to identify the key in your list. Not sent with requests.
Yes
Expires At
Date the key stops working. Leave blank for a key that never expires.
No
Permissions
A grid of every module against View / Create / Update / Delete. The key can only perform the actions you check.
Yes

The key is shown only once

Copy the crbn_… token when it is generated — Carbon stores only a hash and cannot show it again. Keep it server-side; it carries every permission you grant. Lost a key? Delete it and create a new one.

Permissions

Each checkbox grants one action on one module. The action maps to the HTTP method of the request:

Action
Grants
Method
View
Read rows
GET
Create
Insert rows
POST
Update
Modify rows
PATCH
Delete
Remove rows
DELETE

Reading from /item, for example, needs Parts → View. A request for an action the key does not hold returns 403. Some modules omit actions they do not support (Accounting has no Delete, shown as --).

Expiration & errors

If a key is past its Expires At date, requests fail with 401 before anything runs. Other authentication failures:

Status
When it happens
401
Missing or invalid key, or the key has expired.
403
The key lacks the required module permission (or the company is on the Starter plan).
429
Rate limit exceeded — every key allows 60 requests per minute by default, a platform-set limit shown (not editable) in Settings → API Keys. Back off and retry per the X-RateLimit-* and Retry-After response headers.