# Authentication

URL: https://email-validation.org/docs/authentication/
Updated: 2026-10-20

> Documentation index: https://email-validation.org/llms.txt

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:

```http
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](https://email-validation.org/docs/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

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

Report security problems to [security@email-validation.org](mailto: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](https://email-validation.org/docs/errors/).