Keys and access levels

Every request carries the key in the X-API-Key header. You create them in ByDomu, under Settings › API and webhooks; the full key is shown only once.

Publishable and secret

Publishabledomu_pk_live_

For your website and the browser: it can live in the page’s code.

portal:read · leads:write · booking:write · finder:write · events:write

Only public data and receiving clients.

Secretdomu_sk_live_

Server-side only: Zapier, Make, n8n, your backend or an MCP client.

Any permission: *:read and, with approval, *:write

From a browser it returns 403.

Older keys (domu_live_) keep working the same while we review them.

Test mode

Test keys (domu_sk_test_ and domu_pk_test_) have every permission without requesting access and only see your test organization, with sample data: nothing you do with them reaches your clients. Limit: 100 requests and 30 writes per minute.

Test mode guide

Access levels

What a key can do depends on the plan and on what support approves. There is never API access during the free trial or with an unverified email.

LevelPlansHow to get it

1Publishable keys300 requests and 60 writes per minute · up to 5 keysAny paid planNo request

2Read-only secret keys60 requests per minute · up to 2 keysBusiness · EnterpriseAutomatic

3Writes, messages, webhooks and higher limitsTailored to what’s approvedAny paid planSupport review

Higher limits or more permissions are requested from Settings › API and webhooks.

Limits and pagination

Every response tells you what’s left of the minute. Lists are paginated with page and pageSize and include meta.total and meta.totalPages.

Response headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 41
Retry-After: 41            # only with 429
Idempotency-Status: replayed  # retry with the same Idempotency-Key

Errors

Always with the same shape: { "error": { "code", "message" } }.

400VALIDATION_ERRORInvalid input

401UNAUTHORIZEDMissing or invalid key

402PAYMENT_REQUIREDAccount is read-only: write rejected

403FORBIDDENThe key lacks that permission

403SECRET_KEY_IN_BROWSERSecret key used from a browser

403API_ACCESS_REQUIREDThe account’s access level doesn’t allow this key

403PLAN_LIMIT_REACHEDA plan limit was reached

404NOT_FOUNDResource not found

409IDEMPOTENCY_CONFLICTIdempotency-Key reused with a different body

409IDEMPOTENCY_IN_PROGRESSAnother request with the same Idempotency-Key is still running

429RATE_LIMITEDPer-minute limit exceeded

429TENANT_RATE_LIMITEDThe organization’s per-minute write limit was exceeded