# Authentication

Every request carries a secret API key in the `Authorization` header:

```http
Authorization: Bearer sk_live_…
```

## Keys

Keys are created in the dashboard at [app.salchimail.com](https://app.salchimail.com). A key is shown once, when you create it, and SalchiMail stores only a hash of it. If you lose a key, create a new one.

| Prefix | Mode | Behaviour |
| --- | --- | --- |
| `sk_live_` | Live | Real verifications. Uses credits |
| `sk_test_` | Test | Simulated results, no credits. See [Test mode](https://docs.salchimail.com/test-mode.md) |

A key belongs to your organisation, not to a person. Create one key per application or environment and give each a name you will recognise later.

## Keep keys on the server

A key is a secret with access to your credits.

- Call the API from your backend. Never ship a key in a web page, a mobile app or a public repository.
- The API does not send CORS headers, so a request made from a browser will fail by design.
- Load the key from an environment variable or a secret manager, not from source code.

## Check which key you are using

`GET /account` returns the organisation, the plan, the limits and the key behind the request. The secret is never returned, only its `prefix`.

```bash
curl https://api.salchimail.com/v1/account \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY"
```

```json
{
  "id": "org_7a8b9c0d1e2f3a4b",
  "object": "account",
  "livemode": true,
  "name": "Acme Marketing",
  "plan": {
    "id": "basic",
    "status": "active"
  },
  "api_key": {
    "id": "key_2f3a4b5c6d7e8f9a",
    "name": "Production server",
    "prefix": "sk_live_a1b2",
    "created_at": "2026-11-02T08:15:00Z"
  },
  "limits": {
    "requests_per_minute": 600,
    "max_batch_size": 100000,
    "max_concurrent_batches": 3,
    "modes": [
      "basic",
      "mailbox"
    ]
  },
  "created_at": "2026-11-02T08:10:00Z"
}
```

`livemode` is `false` when the request used a `sk_test_` key.

## Rotate a key

1. Create a new key in the dashboard.
2. Deploy it to your application.
3. Revoke the old key. From that moment it answers `401 revoked_api_key`.

## Authentication errors

A request without a usable key answers `401` with the header `WWW-Authenticate: Bearer`:

```json
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
```

| HTTP | `code` | Meaning | What to do |
| --- | --- | --- | --- |
| 401 | `missing_api_key` | No `Authorization: Bearer` header | Send the header on every request |
| 401 | `invalid_api_key` | The key does not exist | Check for a truncated or mistyped key |
| 401 | `revoked_api_key` | The key was revoked in the dashboard | Use a current key |
| 403 | `mode_not_allowed` | The account may not use that `mode` | Check `limits.modes` in `GET /account` |
| 403 | `account_suspended` | The account is suspended | Write to [hola@salchimail.com](mailto:hola@salchimail.com) |

The shape of every error is described in [Limits and errors](https://docs.salchimail.com/limits-and-errors.md).
