Admin API Reference
Server-to-server Admin API — authenticate with an admin API key, identify users from your backend, and review sandbox and live rate limits.
The Admin API is for server-to-server calls from your backend. Use it when user properties live in your systems (billing, CRM, auth) and you want to sync them to Encatch without sending them through a client SDK.
Create and manage admin API keys under Settings in the dashboard. Admin keys authorize admin routes only — they cannot call publishable SDK endpoints.
Server-side only
Admin API keys are secret credentials. Store them on your server. Never embed them in browsers, mobile apps, or public repositories.
Base URL
All Admin API paths are under /v2/admin.
Authentication
Every request must include your admin API key.
Admin (secret) API key for the project
Publishable SDK keys are rejected on admin routes (403). Admin keys are rejected on SDK routes (403).
Endpoints
Rate limits
Admin API traffic is limited per minute on two independent scopes. A request counts against both. If either bucket is exhausted, the API returns 429 Too Many Requests.
Limits depend on whether the project is Sandbox or Live (production). That choice is fixed when the project is created — see Sandbox Environment.
Sandbox projects
Shared by every admin key on the project
Cap for a single admin key
A single admin key in sandbox can send 50 requests/minute. All keys on the same sandbox project share a 100 requests/minute project cap.
Live projects
Shared by every admin key on the project
Cap for a single admin key
A single admin key in a live project can send 4,000 requests/minute. All keys on the same live project share a 10,000 requests/minute project cap.
Both scopes apply
The tighter remaining quota wins. In sandbox, one key hits the 50/min key limit before the 100/min project limit. In live, one key hits 4,000/min before the project hits 10,000/min.
These Admin API limits are separate from SDK rate limits, which apply to publishable-key traffic from the Web and Mobile SDKs.
Rate limit headers
Maximum requests in the current window
Requests left in the current window
When the window resets (Unix timestamp, seconds)
Handling 429
- Wait until X-RateLimit-Reset.
- Retry with exponential backoff.
- Spread traffic across keys only if you are still under the project cap.
Errors
These apply to every Admin API route. Gateway rejections are { "error": "…" }. Unexpected Core API failures return a sanitized 500.
{
"error": "api key is required"
}| Status | When |
|---|---|
401 | Missing X-Api-Key (api key is required) |
401 | Unknown, inactive, expired, or malformed key (invalid api key) |
403 | Publishable SDK key used on an admin route |
429 | Rate limit exceeded |
500 | Unexpected server error. Internal details are not returned |
Route-specific errors (validation, userName, MAU) are documented on each endpoint — start with Identify User.
Was this page helpful?