Authentication
Every request carries an API key in the Authorization header:
Authorization: Bearer $ESSERE_API_KEY
Keys
- Created in the dashboard: Developers → API keys (Pro plan).
vk_live_...keys work against production;vk_test_...keys are issued on staging accounts.- Keys are shown once at creation. We store only a hash — if a key is lost, revoke it and create a new one.
- Keys are account-level: they see every agent on your account.
Scopes
| Scope | Allows |
|---|---|
read |
All GET endpoints. |
read_write |
Everything in read, plus creating/updating contacts and managing webhook endpoints. |
A read key calling a write endpoint gets 403 with code
insufficient_scope.
Plan requirement
The API is a Pro-plan feature, checked at key creation and on every
request. If the account leaves Pro, requests fail with 403 and code
plan_required until the plan is upgraded again — keys are not deleted.
Rate limits
120 requests/minute per key, as a fixed one-minute window (a burst across a window boundary can briefly exceed the nominal rate — throttle to the limit, not the boundary behavior). Every response includes:
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1752841260
On 429, back off for Retry-After seconds. Steady-state polling should
stay well under the limit — prefer webhooks over polling.
Key hygiene
- Keep keys server-side. Never ship them in browser or mobile code.
- Never paste a live key into an AI prompt, chat, or shared document, and
never commit one to source control — use environment variables or a
secret store, and reference them in code (
$ESSERE_API_KEY). - One key per integration, named accordingly — revoke independently.
- Rotate by creating the new key first, deploying it, then revoking the old.
Data processing
Anything you connect through this API — webhook receivers, Zapier or n8n workflows, and any LLM/MCP client — becomes a third-party processor of your call and contact data once you send data to it. Choose processors that meet your own privacy obligations, propagate deletion requests to them, and revoke the API key to cut off access at any time.