Authentication
How to authenticate with the ErzyCall REST API using API keys.
Every request to the ErzyCall REST API must include a valid API key in the X-API-Key header.
Obtaining an API Key
- Navigate to Settings > API Keys in the ErzyCall dashboard
- Click Create API Key
- Give it a name and select the scopes your integration needs
- Optionally set an expiration date
- Copy the key immediately — it is only displayed once
# Example: using the key in a request
curl -X GET "https://app.erzycall.com/api/v1/calls" \
-H "X-API-Key: ek_live_abc123..."Key Format
API keys follow the format ek_{environment}_{random}:
| Prefix | Environment |
|---|---|
ek_live_ | Production |
ek_test_ | Test / Staging |
Scopes
Each API key is assigned one or more scopes that control which endpoints it can access. Use the principle of least privilege — only grant the scopes your integration actually needs.
| Scope | Allows |
|---|---|
* | Full access to all endpoints |
calls:read | List and view calls |
calls:write | Create and cancel calls |
contacts:read | List, view, and search contacts |
contacts:write | Create, update, and delete contacts |
contact_groups:read | List contact groups |
cases:read | List and view cases |
assistants:read | List and view assistants |
assistants:write | Update assistant configuration |
phone_numbers:read | List phone numbers |
webhooks:read | List webhook endpoints |
webhooks:write | Create, update, and delete webhooks |
If a key lacks the required scope for an endpoint, the API returns a 403 error:
{
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "API key lacks required scope: calls:write"
}
}Key Lifecycle
| State | Description |
|---|---|
| Active | Key is valid and can make requests |
| Expired | Key has passed its expiration date — returns 401 KEY_EXPIRED |
| Revoked | Key was manually revoked by an admin — returns 401 KEY_REVOKED |
You can revoke a key at any time from the API Keys settings page. Revocation is immediate and cannot be undone.
Security Best Practices
- Never expose keys in client-side code. API keys should only be used from server-side applications.
- Use environment-specific keys. Create separate keys for test and production environments.
- Set expiration dates. Rotate keys periodically to limit the blast radius of a leak.
- Scope keys narrowly. A read-only integration should not have write scopes.
- Store keys securely. Use environment variables or a secrets manager — never commit keys to source control.
Error Responses
| Status | Code | Meaning |
|---|---|---|
401 | UNAUTHORIZED | Missing or invalid X-API-Key header |
401 | KEY_REVOKED | API key has been revoked |
401 | KEY_EXPIRED | API key has expired |
403 | INSUFFICIENT_SCOPE | Key lacks the required scope |