Authentication

Every API request carries an API key in a header. Keys never go in URLs: a request with a key in the query string is refused with 400 invalid_request, because URLs end up in logs, browser history and Referer headers.

Send the key

Use the Authorization header with the Bearer scheme:

POST /v1/validate HTTP/1.1
Host: api.email-validation.org
Authorization: Bearer ev_live_…
Content-Type: application/json

If your tool cannot set Authorization, send the same key in X-Api-Key instead. Sending both with different values is an error.

Key format

A key is ev_live_ followed by 79 letters and digits (87 characters in total). The last characters are a checksum, so a mistyped key fails fast with 401 unauthorized. The fixed prefix makes a key that leaked into code or logs easy to search for.

Create, roll and revoke keys

Manage keys under API keys in the dashboard. For safety, creating, rolling and revoking a key asks you to confirm it is you.

Create: give the key a name you will recognise later. The full key is shown once; we store only a hash.
Roll: replace a key with a new one. Choose how long the old key keeps working (immediately, 1 hour, 24 hours or 7 days) so you can deploy the new key without downtime.
Revoke: the key stops working at once. Answers for test addresses, which never touch your credits, can follow for up to 10 seconds.

Each key shows when it was last used, so you can spot keys nobody needs any more.

Scopes

Scope	Allows
`validate`	Single checks (`/v1/validate`) and the MCP tool `validate_email`.
`account:read`	Credit balance and usage (`/v1/credits`, `/v1/usage`, MCP `get_credits`).
`bulk`	Bulk jobs (`/v1/bulk…`, MCP `create_bulk_job` and `get_bulk_job`).

New keys get validate and account:read. Turn on bulk only for the keys that need it. A key without the required scope gets 403 forbidden.

Limits per key

Each key can have its own safety limits, set in the dashboard:

Daily credit cap: the most credits the key may use in a day, including the credits held by bulk jobs the key creates or starts. Past the cap, requests get 429 key_daily_cap until the next day, and a bulk job that needs more than the key has left stays ready with error_code: key_daily_cap.
Rate limit: fewer requests per second than the account allows.
Allowed origins: for a key used from browser code, the list of web origins (such as https://app.example.com) it may be used from. Requests from any other Origin get 403 forbidden_origin.

We recommend calling the API from your server and keeping keys out of browser code altogether. If you must call it from a browser, use a dedicated key with allowed origins, a small daily cap and only the validate scope.

If a key leaks

Roll or revoke the key in the dashboard right away.
Check Usage for traffic you do not recognise.
Remove the key from wherever it was exposed (repository history, logs, tickets).

Report security problems to security@email-validation.org.

Errors you may see

HTTP	Code	Cause
400	`invalid_request`	Key in the URL, malformed `Authorization` header, or two different keys.
401	`unauthorized`	No key, a mistyped key, or a revoked or rolled key.
403	`forbidden`	The key lacks the scope, or the account is suspended or on hold.
403	`forbidden_origin`	The key is limited to other browser origins.

All error codes are listed on Errors.