# Autenticación

Cada petición lleva una clave de API secreta en la cabecera `Authorization`:

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

## Claves

Las claves se crean en el panel, en [app.salchimail.com](https://app.salchimail.com). Una clave se muestra una sola vez, al crearla, y SalchiMail solo guarda su hash. Si pierdes una clave, crea otra.

| Prefijo | Modo | Comportamiento |
| --- | --- | --- |
| `sk_live_` | Real | Verificaciones reales. Consume créditos |
| `sk_test_` | Pruebas | Resultados simulados, sin créditos. Consulta [Entorno de pruebas](https://docs.salchimail.com/es/entorno-de-pruebas.md) |

Una clave pertenece a tu organización, no a una persona. Crea una clave por aplicación o entorno y ponle un nombre que reconozcas más adelante.

## Las claves, siempre en el servidor

Una clave es un secreto con acceso a tus créditos.

- Llama a la API desde tu backend. Nunca incluyas una clave en una página web, una aplicación móvil o un repositorio público.
- La API no envía cabeceras CORS, así que una petición hecha desde un navegador fallará por diseño.
- Carga la clave desde una variable de entorno o un gestor de secretos, no desde el código fuente.

## Comprueba qué clave estás usando

`GET /account` devuelve la organización, el plan, los límites y la clave con la que se hizo la petición. El secreto nunca se devuelve, solo su `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` es `false` cuando la petición usó una clave `sk_test_`.

## Rota una clave

1. Crea una clave nueva en el panel.
2. Despliégala en tu aplicación.
3. Revoca la clave antigua. Desde ese momento responde `401 revoked_api_key`.

## Errores de autenticación

Una petición sin una clave utilizable responde `401` con la cabecera `WWW-Authenticate: Bearer`:

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

| HTTP | `code` | Significado | Qué hacer |
| --- | --- | --- | --- |
| 401 | `missing_api_key` | Falta la cabecera `Authorization: Bearer` | Envía la cabecera en todas las peticiones |
| 401 | `invalid_api_key` | La clave no existe | Revisa si está cortada o mal copiada |
| 401 | `revoked_api_key` | La clave se revocó en el panel | Usa una clave vigente |
| 403 | `mode_not_allowed` | La cuenta no puede usar ese `mode` | Consulta `limits.modes` en `GET /account` |
| 403 | `account_suspended` | La cuenta está suspendida | Escribe a [hola@salchimail.com](mailto:hola@salchimail.com) |

La forma de todos los errores se describe en [Límites y errores](https://docs.salchimail.com/es/limites-y-errores.md).
