Docs APIAutenticazione

Autenticazione

Every API request carries one API key in the x-api-key header. The key identifies your workspace and sets what the request may do.

The x-api-key header

Every request to https://beecastly.com/api/v1 carries your key in one header. The key identifies your workspace, so there is nothing else to send.

curl "https://beecastly.com/api/v1/contacts?page=1&limit=20" \
  -H "x-api-key: bk_3f9c…"

A Authorization: Bearer header is a dashboard login session, not an API key — the other dashboard endpoints are not part of the public API and do not accept keys.

Creating a key

Go to Settings → API Keys and click Create key. Only an owner or admin of the workspace can.
Name it after the integration that will use it.
Choose its access:
- Read only — GET requests: list contacts, read a message's status.
- Read & write — also POST: /v1/messages/send and /v1/contacts.
Copy the key from the dialog. It is shown once — only a prefix is stored where you can see it again. Lost it? Delete the key and create a new one.

Error Responses

Errors share one shape: { "success": false, "error": "…", "code": "…" }.

401Unauthorized

The x-api-key header is missing, or the key is unknown, deleted or expired.

{ "success": false, "error": "Invalid API key" }

403Forbidden — API_KEY_PERMISSION

A read-only key called a write endpoint (any POST). Create a Read & write key.

{
  "success": false,
  "error": "This API key does not have the \"write\" permission. …",
  "code": "API_KEY_PERMISSION"
}

429Too Many Requests — API_KEY_RATE_LIMITED

This key went over its per-minute limit (your plan's ceiling, or the key's own limit if lower). Wait for the next minute.

429Too Many Requests — API_DAILY_LIMIT

Your workspace used its plan's API calls for the day. The allowance is shared by all your keys and resets at 00:00 UTC; Retry-After gives the seconds until then.

{
  "success": false,
  "error": "Your plan allows 2,500 API calls per day …",
  "code": "API_DAILY_LIMIT",
  "limit": 2500,
  "resetAt": "2026-10-06T00:00:00.000Z",
  "upgradeUrl": "/select-plan"
}

Limits per plan are listed on the API overview.

Security Best Practices

Never expose API keys in frontend code or Git repositories
Use environment variables to store keys server-side
Rotate keys regularly and revoke unused ones
Give a key Read & write only if the integration sends or creates something