Skip to content
Docs Authentication

Authentication

API keys: format, creation, rotation and error handling.

Every API request authenticates with the X-API-Key header:

request.sh
curl "https://api.kavik.email/api/v1/verify?email=jane@acmecorp.com" \
  -H "X-API-Key: eva_your_key"

Key properties

  • 32-byte random values with the eva_ prefix. Test keys start with eva_test_ and answer the sandbox only.
  • You choose Live or Test when you create a key, and a key cannot switch. A Free account can create test keys only (up to 3); a paying account can hold up to 5 test keys next to its live keys. Any account can create up to 20 test keys in 24 hours.
  • Shown once at creation. Store it somewhere safe; we keep only a bcrypt hash and cannot show it again.
  • Create, name and revoke keys in the dashboard under API keys. Revocation takes effect immediately.
  • All live keys share the account’s plan quota and rate limits. Test keys are never charged and share the sandbox limit of 60 requests a minute per account.
  • Every successful JSON response carries livemode: true for a live key, false for a test key. Error bodies do not.

Errors

Status Meaning
401 Missing, invalid, or revoked key. Response body: {"error": "...", "code": "UNAUTHORIZED"}
403 LIVE_KEY_REQUIRED: a test key was used on a real address or domain. PAID_PLAN_REQUIRED: a live key on an account with no plan and no credits.
429 Rate limit or quota exceeded, with X-RateLimit-* headers to pace by. Top up with a credit pack or upgrade for quota.

Never put a key in client-side code, in a URL, or in a repository. If one leaks, revoke it in the dashboard and create a new one.