# Autenticación

> Autentica las peticiones a la API con una clave de API o un token de acceso OAuth de tipo Bearer, elige el permiso full o sending, limita las claves a un dominio y gestiona los errores de autenticación.

Cada petición a la API de Emailit debe llevar una credencial en la cabecera `Authorization`. Esta página explica los dos tipos de credenciales (claves de API y tokens de acceso OAuth), qué puede hacer cada permiso y todos los errores de autenticación que puedes recibir.

## Claves de API

Una clave de API pertenece a un espacio de trabajo, y cada petición que haces con ella actúa sobre ese espacio de trabajo. Las claves tienen este aspecto:

```text
secret_Xq7pL2mN9vB4kR8tW1yZ6cH3jF5dS0aG
```

Es decir, `secret_` seguido de 32 letras y dígitos. Las claves creadas antes del formato `secret_` no tienen prefijo y siguen funcionando.

Crea claves en el panel, en **Email API → API Keys**, o con [Crear una clave de API](/es/docs/api-reference/api-keys/create/). El secreto se muestra una sola vez, al crear o [regenerar](/es/docs/api-reference/api-keys/regenerate/) la clave, así que guárdalo enseguida. Para gestionarlas, consulta [Claves de API](/es/docs/developers/api-keys/).

Las mismas claves sirven como contraseña SMTP del [SMTP relay](/es/docs/smtp/settings/).

## Enviar la clave con cada petición

Usa el esquema `Bearer` en la cabecera `Authorization`. La API no acepta claves en la cadena de consulta ni en el cuerpo de la petición.

**cURL**

```bash
curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const response = await fetch('https://api.emailit.com/v2/domains', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const domains = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.emailit.com/v2/domains",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
domains = response.json()
```

Los SDK añaden esta cabecera por ti cuando pasas la clave al cliente.

## Permisos

Cada clave tiene uno de dos permisos. Lo eliges al crear la clave y no puedes cambiarlo después.

| Permiso | Puede llamar a | Úsalo para |
| --- | --- | --- |
| `full` | Todos los endpoints de la API. Es el valor por defecto. | Herramientas de back-office, scripts e integraciones que gestionan dominios, contactos, plantillas o webhooks. |
| `sending` | Solo los endpoints de envío que se indican abajo. | Servidores de aplicaciones que solo envían emails. |

Una clave `sending` puede llamar a estos endpoints y a ningún otro:

| Endpoint | Descripción |
| --- | --- |
| `POST /emails` | [Enviar un email](/es/docs/api-reference/emails/send/) |
| `POST /emails/{id}` | [Actualizar un email programado](/es/docs/api-reference/emails/update/) |
| `POST /emails/{id}/cancel` | [Cancelar un email](/es/docs/api-reference/emails/cancel/) |
| `POST /emails/{id}/retry` | [Reintentar un email](/es/docs/api-reference/emails/retry/) |
| `POST /emails/{id}/forward` | [Reenviar un email](/es/docs/api-reference/emails/forward/) |

Para leer emails (listarlos, obtenerlos, y consultar el mensaje en bruto, el cuerpo, los metadatos, los adjuntos y el estado) necesitas una clave `full`. Cuando una clave `sending` llama a cualquier otro endpoint, la API devuelve `403` con `Permission denied: full` (o `Permission denied: read` en los endpoints de lectura de emails).

[Todos los endpoints](/es/docs/api-reference/endpoints/) indica el permiso de cada endpoint.

## Limitar una clave a un dominio

Una clave `sending` también puede limitarse a un dominio de envío. Pasa el ID del dominio como `sending_domain_id` al [crear la clave](/es/docs/api-reference/api-keys/create/). Una clave limitada solo puede enviar desde direcciones de ese dominio. Cualquier otro dominio en `from` devuelve `403`:

```json
{
  "error": "Domain not authorized",
  "message": "API key is not authorized to send from this domain"
}
```

La limitación a un dominio solo se aplica a las claves `sending`. Una clave `full` siempre tiene acceso a todos los dominios del espacio de trabajo.

## Tokens de acceso OAuth

Las aplicaciones que actúan en nombre de un usuario de Emailit, como los clientes MCP y las integraciones de terceros, no piden una clave de API. En su lugar usan OAuth 2.1: el usuario inicia sesión en Emailit, elige los espacios de trabajo que puede usar la aplicación (todos o solo algunos) y aprueba el permiso `sending` o `full`, y la aplicación recibe un token de acceso. El usuario puede cambiar o revocar ese acceso en [Connected apps](/es/docs/account/connected-apps/).

Envía los tokens de acceso en la misma cabecera que las claves de API:

```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…
```

Un token de acceso es válido durante 15 minutos y actúa sobre el espacio de trabajo por defecto de la autorización, con el permiso concedido y el rol del usuario en ese espacio de trabajo. Las aplicaciones lo renuevan con el token de actualización. Para crear una, consulta [Aplicaciones OAuth](/es/docs/developers/oauth-apps/).

## Errores de autenticación

La autenticación se comprueba antes que nada, así que estos errores pueden llegar desde cualquier endpoint.

| Estado | `message` o `error` | Causa | Solución |
| --- | --- | --- | --- |
| `401` | `API key required` | Falta la cabecera `Authorization` o no empieza por `Bearer `. | Envía `Authorization: Bearer <key>`. |
| `401` | `Valid API key required` | La cabecera tiene el prefijo `Bearer` pero no lleva token. | Comprueba que la variable que contiene tu clave no esté vacía. |
| `401` | `Invalid API key` | La clave no existe, se eliminó o se regeneró (el secreto anterior deja de funcionar), o un token OAuth caducó. | Usa una clave vigente o renueva el token OAuth. |
| `403` | `Workspace is suspended` | El espacio de trabajo está suspendido. | Contacta con [soporte](/contact/). |
| `403` | `Permission denied: full` | Una clave `sending` llamó a un endpoint que requiere `full`. | Usa una clave `full`. |
| `403` | `Domain not authorized` | Una clave limitada a un dominio envió desde otro dominio. | Envía desde el dominio de la clave o usa otra clave. |
| `403` | `unverified_workspace_recipient` | El espacio de trabajo aún no está verificado y un destinatario no es miembro del espacio de trabajo. | Consulta [Espacios de trabajo sin verificar](#unverified-workspaces). |
| `503` | `Authentication service unavailable` | Un problema temporal por nuestra parte. | Reintenta con espera exponencial. |

**401**

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

**403 Permiso**

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Permission denied: full"
}
```

**403 Suspendido**

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Workspace is suspended"
}
```

**403 Sin verificar**

```json
{
  "code": "unverified_workspace_recipient",
  "error": "Workspace not verified",
  "message": "Unverified workspaces can only send to workspace members' account emails. Blocked recipient: ada@example.com.",
  "blocked_recipients": ["ada@example.com"]
}
```

## Espacios de trabajo sin verificar

Los espacios de trabajo nuevos empiezan sin verificar. Hasta que Emailit aprueba el [acceso de producción](/es/docs/workspaces/production-access/), la API solo envía a las direcciones de email de las cuentas de los miembros del espacio de trabajo. Enviar, reintentar o reenviar a cualquier otra dirección devuelve `403` con el código `unverified_workspace_recipient` y la lista `blocked_recipients`, y las campañas no se pueden enviar en absoluto. Tus claves de API funcionan con normalidad para todo lo demás.

## Mantener tus claves en secreto

Una clave de API da acceso a tu espacio de trabajo, así que trátala como una contraseña.

- Llama a la API solo desde tu servidor. No pongas nunca una clave en el JavaScript del navegador, en una aplicación móvil ni en ningún otro código que se ejecute en el dispositivo de otra persona.
- No guardes las claves en el control de versiones. Cárgalas desde variables de entorno o desde un gestor de secretos.
- Crea una clave por aplicación y entorno, y ponle un nombre que indique dónde se usa, para poder revocar una sin afectar a las demás.
- Da a cada clave el mínimo acceso que necesite: una clave `sending` limitada a un dominio basta para la mayoría de las aplicaciones.
- Comprueba `last_used_at` en [Listar claves de API](/es/docs/api-reference/api-keys/list/) y elimina las claves que ya no uses.
- Si se filtra una clave, [regenérala](/es/docs/api-reference/api-keys/regenerate/) o [elimínala](/es/docs/api-reference/api-keys/delete/) de inmediato. El secreto anterior deja de funcionar al instante.

## Ver también

  - [Claves de API](/es/docs/developers/api-keys/): Crea, limita y rota claves en el panel.
  - [Errores](/es/docs/api-reference/errors/): Todos los formatos de error y códigos de estado.
  - [Aplicaciones OAuth](/es/docs/developers/oauth-apps/): Permite que los usuarios conecten tu aplicación a su espacio de trabajo.
  - [Acceso de producción](/es/docs/workspaces/production-access/): Consigue la verificación de tu espacio de trabajo para enviar a cualquier destinatario.

---
Fuente: https://emailit.com/es/docs/api-reference/authentication/