# Claves de API

> Crea claves de API Full Access y Sending Only, limítalas a un dominio, úsalas para SMTP y rótalas sin interrupciones.

Las claves de API autentican tus peticiones a la API REST, tus conexiones SMTP y las sesiones con clave de API en el servidor MCP. En esta página se explican los dos permisos que puede tener una clave, cómo crear y gestionar claves y cómo guardarlas y rotarlas de forma segura.

## Cómo funcionan las claves de API

- Cada clave pertenece a un espacio de trabajo. Todo lo que haces con ella ocurre en ese espacio de trabajo.
- Las claves nuevas empiezan por `secret_` seguido de 32 letras y dígitos, por ejemplo `secret_••••••••`. Las claves creadas antes de que se introdujera el prefijo siguen funcionando.
- Emailit muestra la clave completa una sola vez, al crearla o regenerarla. Cópiala en ese momento; no podrás volver a verla.
- La clave se envía como token bearer: `Authorization: Bearer secret_…`. En SMTP, la clave es la contraseña.

## Permisos

Cada clave tiene uno de estos dos permisos. El permiso se elige al crear la clave.

| | Full Access (`full`) | Sending Only (`sending`) |
| --- | --- | --- |
| Enviar emails (`POST /emails`) | Sí | Sí |
| Reprogramar, cancelar, reintentar y reenviar un email | Sí | Sí |
| SMTP relay | Sí | Sí |
| Leer emails (listar, obtener, mensaje en bruto, cuerpo, metadatos, adjuntos) | Sí | No |
| Dominios, plantillas, contactos, listas de contactos, direcciones bloqueadas, webhooks, eventos, campañas, automatizaciones, verificación de emails y claves de API | Sí | No |
| Herramientas MCP | Todas las herramientas | `send-email`, `update-email`, `cancel-email`, `retry-email`, `forward-email` y `get-current-workspace` |
| Se puede limitar a un dominio de envío | No | Sí |

Una clave Sending Only que llama a cualquier otro endpoint recibe `403` con un mensaje como `Permission denied: read`. Usa claves Full Access para las tareas internas que gestionan recursos y claves Sending Only para todo lo que solo necesita enviar.

### Limitar una clave a un dominio

Al crear una clave Sending Only, puedes elegir un dominio de envío verificado. Así, la clave solo puede enviar desde direcciones de ese dominio:

- Por la API, enviar desde otro dominio devuelve `403` con `"error": "Domain not authorized"`.
- Por SMTP, el mensaje se rechaza después de `DATA` con `530 API key is restricted to sending domain: …`.

Las claves limitadas son una buena opción para credenciales por aplicación o por cliente, y para las claves que tienes que dar a software de terceros, como el plugin de un CMS.

## Antes de empezar

- Necesitas el rol **Admin** en el espacio de trabajo para crear, editar, regenerar o eliminar claves. Los miembros pueden ver la lista de claves, pero no modificarla. Consulta [Miembros y roles](/es/docs/workspaces/members-and-roles/).
- Para enviar con una clave, necesitas al menos un [dominio de envío verificado](/es/docs/domains/add-a-domain/).

## Crear una clave de API

**Panel**

  1. **Abre las claves de API.** Ve a **Email API → API Keys** y selecciona **Add API key**.

  2. **Ponle nombre a la clave.** Introduce un **Name** que indique dónde se usa la clave, por ejemplo `production-web` o `wordpress-blog`. Los nombres deben ser únicos en el espacio de trabajo.

  3. **Elige un permiso.** En **Scope**, elige **Full Access** o **Sending Only**.

  4. **Si quieres, limita el dominio.** En una clave Sending Only, elige un dominio de envío en **Domain** o déjalo vacío para permitir todos los dominios verificados.

  5. **Crea y copia la clave.** Selecciona **Create**. Copia la clave del cuadro de diálogo y guárdala en tu gestor de secretos antes de cerrarlo. Emailit muestra la clave una sola vez.

**API**

  Llama a [Crear una clave de API](/es/docs/api-reference/api-keys/create/) con una clave Full Access. `scope` es `full` por defecto; `sending_domain_id` solo se aplica a las claves Sending Only.

```bash
curl https://api.emailit.com/v2/api-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-web",
    "scope": "sending",
    "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6"
  }'
```

  La respuesta `201` es la única que incluye `key`:

```json
{
  "object": "api_key",
  "id": "key_4F2kN8sQwE1rT6yU3iO9pA7sD5f",
  "name": "production-web",
  "scope": "sending",
  "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6",
  "last_used_at": null,
  "created_at": "2026-10-01T09:30:00.000Z",
  "updated_at": "2026-10-01T09:30:00.000Z",
  "key": "secret_••••••••••••••••••••••••••••••••"
}
```

  Un nombre que ya está en uso devuelve `409`.

## Usar la clave

Pasa la clave en la cabecera `Authorization` de cada petición a la API:

```bash
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Your order has shipped",
    "text": "Your order #1042 is on its way."
  }'
```

Para enviar por SMTP, usa la clave como contraseña:

| Ajuste | Valor |
| --- | --- |
| Host | `smtp.emailit.com` |
| Puerto | `587` (STARTTLS, recomendado), `465` (TLS), `2525` o `2587` (STARTTLS) |
| Usuario | `emailit` |
| Contraseña | Tu clave de API |

Para ver todas las opciones, consulta [Configuración SMTP](/es/docs/smtp/settings/).

## Gestionar las claves

Abre una clave desde **Email API → API Keys** para ver su permiso, su dominio, la fecha **Created**, la hora **Last used** y la configuración SMTP que debes usar con ella.

| Acción | Qué ocurre | API |
| --- | --- | --- |
| **Edit** | Cambia el nombre de la clave. Solo se guarda el nombre; para cambiar el permiso o la limitación de dominio, crea una clave nueva y rota a ella. | [Actualizar una clave de API](/es/docs/api-reference/api-keys/update/) |
| **Regenerate** | Genera un secreto nuevo para la misma clave y lo muestra una vez. El secreto anterior deja de funcionar de inmediato. La clave conserva su ID, su nombre, su permiso y su dominio, y **Last used** se reinicia. | [Regenerar una clave de API](/es/docs/api-reference/api-keys/regenerate/) |
| **Delete** | La clave deja de funcionar de inmediato y desaparece de la lista. Esta acción no se puede deshacer. | [Eliminar una clave de API](/es/docs/api-reference/api-keys/delete/) |

**Last used** se actualiza cada vez que la clave autentica una petición a la API o un inicio de sesión SMTP. Una clave que nunca se ha usado muestra **Never**. En la API, los endpoints que reciben el ID de una clave también aceptan su nombre.

## Guardar las claves de forma segura

- **Mantén las claves en el servidor.** No pongas nunca una clave en el JavaScript del navegador, en una app móvil, en un repositorio público ni en un ticket de soporte. Cualquiera que tenga la clave puede enviar emails en tu nombre y gastar tus créditos.
- **Usa variables de entorno o un gestor de secretos.** Carga la clave en tiempo de ejecución, por ejemplo desde `EMAILIT_API_KEY`. Añade los archivos `.env` a `.gitignore`.
- **Da a cada aplicación y a cada entorno su propia clave.** Con claves separadas para producción, preproducción y cada herramienta de terceros, es fácil ver quién envió qué y revocar una sin tocar las demás.
- **Usa el permiso más limitado.** Si una aplicación solo envía emails, dale una clave Sending Only, limitada a su dominio siempre que sea posible.
- **Vigila el uso.** **Email API → Logs** muestra las peticiones a la API y SMTP por clave, y puedes filtrar **Email API → Emails** por clave de API. Consulta [Registros de peticiones](/es/docs/logs/request-logs/).
- **Actúa rápido ante una filtración.** Si una clave queda expuesta, regenérala o elimínala de inmediato y después revisa los registros en busca de envíos inesperados.

## Rotar una clave sin interrupciones

Regenerar una clave anula el secreto anterior al instante, así que hazlo solo cuando una clave esté comprometida. Para una rotación planificada, usa la clave antigua y la nueva en paralelo:

1. **Crea una clave nueva.** Añade una clave con el mismo permiso y la misma limitación de dominio que la que vas a sustituir. Ponle un nombre que indique la fecha, como `production-web-2026-10`.

2. **Despliega la clave nueva.** Actualiza el secreto en tu gestor de secretos o en tu entorno y llévalo a todos los servidores, workers y tareas programadas que usan la clave antigua.

3. **Confirma el cambio.** Abre la clave nueva y comprueba que **Last used** es reciente. En **Email API → Logs**, filtra por la clave antigua y comprueba que ya no llegan peticiones.

4. **Elimina la clave antigua.** Cuando la hora **Last used** de la clave antigua deje de cambiar, elimínala.

## Solución de problemas

| Síntoma | Causa | Solución |
| --- | --- | --- |
| `401` `Invalid API key` | La clave se eliminó, se regeneró o se escribió mal. | Copia la clave actual en tu configuración, con el prefijo `secret_`. |
| `403` `Permission denied: read` o `Permission denied: full` | Una clave Sending Only llamó a un endpoint fuera de su permiso. | Usa una clave Full Access para esa llamada. |
| `403` `Domain not authorized` | La clave está limitada a un dominio distinto del de la dirección `from`. | Envía desde el dominio de la clave o usa otra clave. |
| SMTP `535 Authentication failed` | La contraseña no es una clave de API válida. | Usa la clave de API como contraseña y `emailit` como usuario. |

## Ver también

  - [Autenticación](/es/docs/api-reference/authentication/): Cómo se autentican las peticiones.
  - [API de claves de API](/es/docs/api-reference/api-keys/): Crea, lista, actualiza, regenera y elimina claves.
  - [Configuración SMTP](/es/docs/smtp/settings/): Host, puertos, TLS y credenciales.
  - [Seguridad](/es/docs/security/): Cómo protege Emailit tu cuenta y tus datos.

---
Fuente: https://emailit.com/es/docs/developers/api-keys/