# auth.md: email-validation.org

You are an agent. email-validation.org authenticates API, MCP and A2A calls with an **API key** sent as a bearer token.
There is no OAuth flow and no agentic self-registration: a person creates the key for you in the dashboard. Follow
the steps in order.

## Step 1: get a key from the account owner

1. The owner signs up or signs in at https://email-validation.org/signin/ (email code, Google or passkey). New accounts get
   500 free credits.
2. In the dashboard, under **API keys**, they create a key for you and give it a name they will recognise.
   The full key (`ev_live_…`, 87 characters) is shown once.
3. They hand it to you through a secret store or an environment variable (for example `EV_API_KEY`), never
   in a URL, a chat transcript or committed code.

If you do not have a key, stop and ask the owner for one. Do not try to sign up or create keys yourself.

## Step 2: send it on every request

```http
Authorization: Bearer <your API key>
```

The same key works for:

- REST: https://api.email-validation.org/v1/… (OpenAPI: https://api.email-validation.org/openapi.json)
- MCP: https://api.email-validation.org/mcp (server card: https://email-validation.org/.well-known/mcp/server-card.json)
- A2A: https://api.email-validation.org/a2a (agent card: https://api.email-validation.org/.well-known/agent-card.json)

If a tool cannot set `Authorization`, send the key in `X-Api-Key` instead. A key in a query string
is refused with `400 invalid_request`.

## What a key may do

| Scope | Allows |
|---|---|
| `validate` | Single checks: REST /v1/validate, MCP validate_email, A2A validate_email. |
| `bulk` | Bulk jobs: REST /v1/bulk…, MCP create_bulk_job and get_bulk_job. |
| `account:read` | Credit balance and usage: REST /v1/credits and /v1/usage, MCP and A2A get_credits. |

New keys get `validate` and `account:read`. The owner can also give a key a **daily credit cap**, a
lower **rate limit** and a list of **allowed browser origins**. Past the cap, calls get `429 key_daily_cap`
until the next day; a missing scope gets `403 forbidden`.

## Limits

- Up to 500 requests per second per account after a purchase
  (20 per second before).
- On `429` or `503`, wait for the `Retry-After` header, then retry.
- One credit per definite result; `unknown` results and errors are free.

## When the key stops working

`401 unauthorized` means the key is missing, mistyped, revoked or rolled. The owner can revoke a key (it stops
working at once) or roll it (the old key keeps working for the period they choose: none, 1 hour, 24 hours or 7 days).
Ask the owner for the new key; do not retry with the old one.

If a key may have leaked, tell the owner to roll or revoke it in the dashboard right away, and report security
problems to security@email-validation.org.

## More

- Authentication: https://email-validation.org/docs/authentication/
- Errors: https://email-validation.org/docs/errors/ · Rate limits: https://email-validation.org/docs/rate-limits/
- AI agents (MCP, A2A, Agent Skills, discovery files): https://email-validation.org/docs/ai-agents/
- Agent skill: https://email-validation.org/.well-known/agent-skills/email-validation/SKILL.md