# Keys and access levels

> Publishable and secret keys, test mode, access levels, per-minute limits and errors of the ByDomu API.


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

**Publishable** `domu_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.

**Secret** `domu_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](https://developers.bydomu.com/en/guias/modo-de-prueba)

## 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.

Level Plans How to get it

1 **Publishable keys** 300 requests and 60 writes per minute · up to 5 keys Any paid plan No request

2 **Read-only secret keys** 60 requests per minute · up to 2 keys Business · Enterprise Automatic

3 **Writes, messages, webhooks and higher limits** Tailored to what’s approved Any paid plan Support 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" } }`.

**400** `VALIDATION_ERROR` Invalid input

**401** `UNAUTHORIZED` Missing or invalid key

**402** `PAYMENT_REQUIRED` Account is read-only: write rejected

**403** `FORBIDDEN` The key lacks that permission

**403** `SECRET_KEY_IN_BROWSER` Secret key used from a browser

**403** `API_ACCESS_REQUIRED` The account’s access level doesn’t allow this key

**403** `PLAN_LIMIT_REACHED` A plan limit was reached

**404** `NOT_FOUND` Resource not found

**409** `IDEMPOTENCY_CONFLICT` Idempotency-Key reused with a different body

**409** `IDEMPOTENCY_IN_PROGRESS` Another request with the same Idempotency-Key is still running

**429** `RATE_LIMITED` Per-minute limit exceeded

**429** `TENANT_RATE_LIMITED` The organization’s per-minute write limit was exceeded