> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Administradores y claves API

> Invita administradores y crea claves API limitadas a las partes del espacio de trabajo que necesitan, cambia sus permisos cuando quieras y consulta qué permite cada permiso.

![Configuración, Equipo y claves API: los miembros, una invitación pendiente y dos claves API](https://www.notifuse.com/docs/assets/screenshots/api_key.png)

## Gestión de administradores

### Invitar administradores

- Solo el propietario del espacio de trabajo puede invitar a nuevos administradores.
- Eliges los permisos que lleva la invitación y puedes cambiarlos más adelante.
- Las invitaciones se envían por correo.

El propietario tiene todos los permisos y no se le puede restringir. Todos los demás, tanto administradores humanos como claves API, tienen el conjunto de permisos que tú elijas.

### Permisos

> [!NOTE]
>
> **Autoalojado: guardar un conjunto de permisos que no sea el acceso completo requiere una [clave de licencia](https://www.notifuse.com/es/docs/self-hosting/licence.md).** Esto incluye definir los permisos de un miembro, invitar con un conjunto restringido y crear una clave API con un alcance restringido. Sin licencia, los nuevos miembros y las nuevas claves reciben acceso completo. Los permisos ya concedidos se siguen aplicando en cualquier estado de licencia, y quitar a un miembro siempre está permitido, porque así se revoca una clave filtrada. Notifuse Cloud incluye permisos granulares a partir del plan Starter ([detalles](https://www.notifuse.com/es/docs/self-hosting/licence.md#on-notifuse-cloud)).

Un permiso es un par de interruptores sobre un área del espacio de trabajo: uno de lectura (**Leído**) y uno de escritura (**Escribir**). La escritura no implica la lectura, y los dos están desactivados salvo que se concedan. La barra lateral de la consola muestra una sección cuando el miembro tiene activado cualquiera de los dos interruptores de su área.

Puedes cambiar los permisos de un miembro desde la página Equipo y claves API en cualquier momento. El cambio se aplica a partir de su siguiente petición.

## Gestión de claves API

### Crear claves API

- Solo el propietario del espacio de trabajo puede crear una clave API.
- Eliges los permisos de la clave al crearla, o se los concedes todos.
- El token se muestra una sola vez, al crear la clave.

![Los permisos de una clave API, con interruptores de lectura y escritura para cada recurso](https://www.notifuse.com/docs/assets/screenshots/api_key_permissions.png)

Una clave creada sin elegir permisos tiene acceso completo al espacio de trabajo. Las claves creadas antes de que existieran los permisos con alcance se comportan igual hasta que las limites. Una clave creada con todos los permisos desactivados aún puede autenticarse y llegar a los pocos endpoints que no requieren ningún permiso: `/api/workspaces.list` devuelve el registro del espacio de trabajo al que pertenece la clave (su configuración, las etiquetas de los campos personalizados y los bloques de plantilla reutilizables guardados en él), con las credenciales de los proveedores ocultas. Todo lo que aparece en la tabla de abajo le está cerrado.

Dale a cada integración su propia clave con los permisos mínimos que necesite. Una clave que solo envía correo transaccional solo necesita la escritura de Transaccional (consulta [API transaccional](https://www.notifuse.com/es/docs/features/transactional-api.md)). [Zapier](https://www.notifuse.com/es/docs/integrations/zapier.md) fija su propio alcance: al conectarlo desde **Configuración** → **Integraciones** se crea una clave con lectura y escritura de Suscripciones de webhook, Contactos y Listas, más la lectura de Segmentos.

El prefijo que elijas pasa a ser la dirección de correo API de la clave y el nombre de usuario del puente SMTP. Admite letras minúsculas, dígitos, guiones y guiones bajos, hasta 64 caracteres, y solo puede usarse una vez por instalación de Notifuse.

### Cambiar el alcance de una clave

Puedes ampliar o reducir una clave existente en cualquier momento desde la página Equipo y claves API. El cambio se aplica a partir de la siguiente petición de la clave. **El token no cambia**, así que no tienes que volver a emitir nada ni actualizar ninguna integración.

### Seguridad

- Copia y guarda el token en cuanto se cree la clave.
- Un token perdido no se puede recuperar: crea una clave nueva.
- Todas las llamadas a la API deben usar HTTPS.

Cuando se rechaza una clave, la API responde `403` e indica el área que falta (`contacts`, `webhook_subscriptions`, etc.) y el interruptor que falta. Un `403` por cuota no lleva ninguna de las dos cosas, así que es fácil distinguirlos.

## Revocar una clave

> [!WARNING]
>
> Eliminar la clave es la única forma de revocarla, y no tiene vuelta atrás: el token sigue siendo válido
> hasta que se elimina la clave, y una clave eliminada no se puede restaurar ni volver a emitir. Todas las
> integraciones que la usan dejan de funcionar en el momento en que la eliminas.

Conviene saber estos dos puntos antes de un incidente:

- **Reducir una clave no es revocarla.** Una clave sin ningún permiso sigue autenticándose y conserva el acceso que no requiere permiso. Reduce una clave para contenerla, no para anularla.
- **No puedes saber qué clave se filtró.** Las claves no guardan la fecha de último uso ni un registro de peticiones por clave, así que si sospechas que un token quedó expuesto pero no tienes el token en sí, Notifuse no puede decirte de qué clave se trata. Con varias claves en uso, la única respuesta segura es eliminarlas todas, crear otras nuevas y actualizar cada integración.

No siempre eliminas una clave desde la página Equipo y claves API: al borrar una conexión de [Zapier](https://www.notifuse.com/es/docs/integrations/zapier.md) desde **Configuración** → **Integraciones** se elimina la clave que creó, y al borrar un espacio de trabajo se eliminan todas sus claves. Eliminar la clave de una conexión de Zapier desde Equipo y claves API también la revoca, pero deja la tarjeta de la conexión, que apunta a una clave que ya no existe.

Por eso conviene tener pocas claves, darle a cada una un prefijo que nombre el sistema que la usa y preferir claves limitadas, para que una filtración te cueste una integración y no el espacio de trabajo.

## Qué permite cada permiso

> [!NOTE]
>
> Cuando una versión introduce un permiso nuevo, los miembros y las claves API existentes lo reciben al
> actualizar. Una clave que limitaste a propósito se amplía así con la nueva área y se queda así
> hasta que vuelvas a limitarla, de modo que revisa tus claves limitadas después de cada actualización. Una clave con _todos_
> los permisos desactivados es una excepción: la actualización no la toca.
>
> **La lectura de Registros de auditoría es la segunda excepción**, y el único permiso que funciona así: nunca
> se rellena al actualizar y no forma parte del acceso completo. Concédelo solo a las personas y claves
> que deban leer la dirección de correo, la dirección IP y las acciones rechazadas de cada colega.

En la consola, haz clic en el nombre de un permiso en la matriz para ver los endpoints que controla y qué hace cada uno. La tabla de abajo los resume.

| Permiso                      | Con lectura                                                                                                                                                                                                                                                                                                                           | Con escritura                                                                                                                                                                                                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contactos**                | Ver los contactos y sus perfiles completos, su historial y los eventos personalizados registrados para ellos. También es necesario para listar las direcciones de una lista o un segmento, y para poner `cc` o `bcc` en un envío transaccional                                                                                        | Crear y actualizar contactos, **eliminarlos**, **sobrescribir todos los campos en bloque** mediante una importación CSV o por API, y registrar eventos personalizados                                                                                                      |
| **Segmentos**                | Ver los segmentos y sus definiciones, y el estado de sus tareas de construcción. Previsualizar un segmento, o listar los contactos que coinciden con él, también requiere la lectura de Contactos                                                                                                                                     | Crear, editar, eliminar y reconstruir segmentos, y ejecutar, reiniciar o eliminar sus tareas de construcción                                                                                                                                                               |
| **Listas**                   | Ver las listas, su configuración y su número de suscriptores. Listar los miembros de una lista también requiere la lectura de Contactos                                                                                                                                                                                               | Crear, editar y eliminar listas, y **suscribir una dirección a cualquier lista, pública o no, lo que crea o sobrescribe el registro de ese contacto en la misma llamada**. Cambiar o quitar una suscripción existente también requiere la escritura de Contactos           |
| **Plantillas**               | Ver las plantillas en todos los idiomas y los bloques de plantilla reutilizables, y compilar una plantilla con datos de prueba. Junto con la escritura de Transaccional, también es necesario para enviar un correo de prueba y para crear o editar una notificación transaccional                                                    | Crear, editar y eliminar plantillas y bloques reutilizables. Editar un bloque no cambia las plantillas que ya lo contienen                                                                                                                                                 |
| **Blog**                     | Ver las categorías, las entradas incluidos los borradores sin publicar y las versiones del tema incluidos sus scripts                                                                                                                                                                                                                 | Crear, editar, eliminar, publicar y despublicar entradas y categorías; **publicar un tema**; y cambiar la configuración del blog, incluido activarlo o desactivarlo                                                                                                        |
| **Envíos masivos**           | Ver los envíos masivos, su configuración y los resultados de sus pruebas A/B, y el estado de sus tareas de envío. Las estadísticas de entrega dependen de la lectura de Historial de mensajes                                                                                                                                         | Crear y editar envíos masivos, actualizar y probar los feeds de datos, y programar, **enviar a toda la audiencia**, pausar, reanudar, cancelar y eliminar un envío masivo, elegir la variante ganadora de la prueba A/B, y ejecutar o reiniciar la tarea de envío asociada |
| **Transaccional**            | Ver las definiciones de las notificaciones transaccionales                                                                                                                                                                                                                                                                            | Crearlas, editarlas y eliminarlas, y enviar correo real: por la API, por el puente SMTP y como prueba de plantilla. Probar un proveedor de correo sigue reservado al propietario. Consulta [las reglas de envío](#transactional-sending-and-contacts) más abajo            |
| **Automatizaciones**         | Ver las automatizaciones, la configuración completa de sus nodos incluidas las URL y los secretos bearer de los nodos webhook, y el recorrido de un contacto concreto por un flujo                                                                                                                                                    | Crear, editar y eliminar automatizaciones, y activarlas o pausarlas                                                                                                                                                                                                        |
| **Historial de mensajes**    | Ver los mensajes enviados con las direcciones de sus destinatarios y los datos renderizados, y los recuentos de entregas, aperturas, clics, rebotes y clics por enlace de un envío masivo                                                                                                                                             | **Nada: este verbo no controla nada por ahora**                                                                                                                                                                                                                            |
| **Analíticas web**           | Ver las analíticas del sitio, las anotaciones dibujadas en esos gráficos y el progreso de la importación histórica                                                                                                                                                                                                                    | Crear, editar y eliminar anotaciones, iniciar y cancelar la importación histórica, y cambiar la configuración de la analítica web (dominios permitidos, filtros, etiquetas de las dimensiones personalizadas e identificación por enlaces de correo)                       |
| **Suscripciones de webhook** | Listar las suscripciones y abrir una, y leer el registro de entregas, con el payload de cada evento y la respuesta del endpoint. El secreto de firma está oculto para todos salvo para el propietario                                                                                                                                 | Crear, editar, eliminar, activar y desactivar suscripciones, y lanzar una entrega de prueba                                                                                                                                                                                |
| **Eventos de webhook**       | Ver los callbacks sin procesar que te devuelven tus proveedores de correo, con las direcciones de los destinatarios y los diagnósticos del proveedor                                                                                                                                                                                  | **Nada: este verbo no controla nada por ahora**                                                                                                                                                                                                                            |
| **Registros de auditoría**   | Leer el [historial de auditoría](https://www.notifuse.com/es/docs/features/audit-logs.md) y exportarlo: quién hizo qué en el espacio de trabajo, con la dirección de correo del actor, la dirección IP desde la que llegó y las acciones que se le rechazaron. **Nunca lo concede el "acceso completo"** (consulta la nota de arriba) | **Nada: este verbo no controla nada por ahora.** La plataforma escribe las entradas, y la retención es un ajuste reservado al propietario                                                                                                                                  |
| **LLM**                      | **Nada: este verbo no controla nada por ahora**                                                                                                                                                                                                                                                                                       | Usar el asistente de IA                                                                                                                                                                                                                                                    |
| **Espacio de trabajo**       | Leer el registro del espacio de trabajo y su configuración, y ver todo el equipo: miembros, propietarios, claves API e invitaciones pendientes. Sin él, la lista del equipo muestra solo tu propia fila en lugar de rechazar la petición                                                                                              | Renombrar las etiquetas de los campos de contacto personalizados del espacio de trabajo, y ejecutar, reiniciar o eliminar una tarea de sincronización de una integración. **Nada más** (consulta más abajo)                                                                |

Dos familias de endpoints son compartidas y comprueban el permiso que corresponde a la petición: `/api/analytics.query` comprueba el permiso de cada esquema que consultas, y `/api/tasks.*` comprueba el permiso del tipo de tarea (Segmentos para las construcciones de segmentos, Envíos masivos para los envíos, Analíticas web para las importaciones históricas, Espacio de trabajo para las sincronizaciones de integraciones).

### Verbos que hoy no controlan nada

Cuatro interruptores no tienen ningún endpoint detrás en la API actual: **la lectura de LLM**, **la escritura de Historial de mensajes**, **la escritura de Eventos de webhook** y **la escritura de Registros de auditoría**. La consola muestra los cuatro concedidos y bloqueados, y no puedes desactivarlos. Guardar uno como "desactivado" sería permanente: al rellenar un permiso que falta solo se añade lo que le falta a una concesión, así que nada lo activaría si una versión posterior le diera al verbo algo que controlar.

Concederlos no da nada, porque el trabajo se hace en otra parte. El asistente de IA depende de la escritura de LLM. El historial de mensajes es de solo lectura porque es el proceso de envío el que escribe sus filas. Los callbacks entrantes de los proveedores llegan por rutas que no llevan sesión ni comprueban ningún permiso. La plataforma escribe el historial de auditoría por sí misma, y el único ajuste modificable del historial, la retención, está reservado al propietario y no depende de ningún permiso.

### La escritura de Espacio de trabajo cubre menos de lo que parece

El único ajuste del espacio de trabajo que el permiso **Espacio de trabajo** te deja cambiar son las etiquetas de los campos de contacto personalizados. **No** cubre:

- Renombrar el espacio de trabajo, cambiar su configuración general o eliminarlo: reservado al propietario.
- Crear, actualizar o eliminar una integración: reservado al propietario. La escritura de Espacio de trabajo no lo concede, y un propietario lo tiene sin ella.
- La configuración del blog, que depende de la escritura de Blog.
- La configuración de la analítica web, que depende de la escritura de Analíticas web.

Así que dar a alguien el blog o la analítica del sitio también le da la configuración de esa función a nivel de espacio de trabajo, incluido el interruptor que la activa o la desactiva.

## Acciones reservadas al propietario

Ningún permiso concede estas acciones. Quedan en manos del propietario del espacio de trabajo, tenga lo que tenga un miembro o una clave:

- Renombrar el espacio de trabajo, cambiar su configuración general y eliminarlo
- Crear, actualizar y eliminar integraciones, y los endpoints de configuración de Amazon SES
- Registrar webhooks en un proveedor de correo, porque usa las credenciales del proveedor guardadas en tu integración
- Probar un proveedor de correo, lo que envía un correo de prueba con las credenciales del proveedor guardadas en tu integración
- Regenerar el secreto de firma de una suscripción de webhook, y leerlo (está oculto para todos los demás)
- Invitar a un miembro, quitar a un miembro y definir los permisos de un miembro
- Crear una clave API
- Transferir la propiedad del espacio de trabajo

## Permisos que van más allá de su nombre

Lee esto antes de concederlos a una clave que no controlas del todo.

- **La escritura de Contactos elimina y sobrescribe en bloque.** Cubre `/api/contacts.delete`, y cubre `/api/contacts.import`, que sobrescribe todos los campos que trae cada fila: una sola llamada puede reescribir toda tu base de contactos. La lectura de Contactos también va más allá de los perfiles: cubre el historial del contacto y los eventos personalizados.
- **La escritura de Listas es una escritura de Contactos implícita.** Suscribir una dirección mediante `/api/lists.subscribe` crea o sobrescribe el registro completo de ese contacto con todos los campos que trae la petición, **sin necesitar la escritura de Contactos**, así que una clave que solo tiene la escritura de Listas puede reescribir datos de contactos. La misma llamada puede suscribir a alguien a una lista que no es pública. Concede la escritura de Listas solo donde concederías la escritura de Contactos.
- **La escritura de Envíos masivos envía.** El interruptor que permite a alguien redactar una campaña también le permite enviarla a toda tu audiencia, mediante `/api/broadcasts.schedule` o lanzando o reiniciando la tarea de envío asociada.
- **La escritura de Automatizaciones lee contactos, cambia listas y envía correo.** Un nodo webhook envía el registro completo del contacto a cualquier URL que indique la automatización, y nada comprueba los permisos mientras se ejecuta una automatización. Otros nodos añaden y quitan contactos de listas y envían correo. Este interruptor llega así a los datos de contactos, a la pertenencia a listas y al envío sin ningún permiso de Contactos, Listas o Transaccional.
- **La lectura de Automatizaciones expone secretos.** La configuración de los nodos webhook que devuelve incluye los tokens bearer configurados en esos nodos.
- **La escritura de Blog ejecuta JavaScript en tu dominio.** Incluye publicar un tema, cuyo propio `scripts.js` se sirve a todos los visitantes del dominio personalizado de tu blog. También activa y desactiva la función de blog.
- **Plantillas cubre los bloques reutilizables.** Quien tiene la escritura de Plantillas puede editar, sustituir o eliminar los bloques guardados del espacio de trabajo. Las plantillas existentes conservan su propia copia y las inserciones futuras reciben el bloque actualizado. Los bloques se guardan con la configuración del propio espacio de trabajo, así que su contenido también aparece en el registro del espacio de trabajo.
- **Analíticas web cubre las anotaciones.** Las anotaciones no tienen permiso propio, así que esta concesión también permite escribir en la línea de tiempo compartida que todos leen. El recolector público de seguimiento no depende de ningún permiso: acepta datos sin autenticación.
- **La escritura de Suscripciones de webhook recibe datos de contactos y de correo.** Una suscripción elige los eventos que transporta, así que quien tiene este permiso puede suscribirse a eventos de contactos y de correo y hacer que esos datos se entreguen en cualquier URL. La lectura abre el registro de entregas, que contiene los propios payloads. Consulta [Webhooks](https://www.notifuse.com/es/docs/features/webhooks.md).
- **La lectura de Segmentos más la lectura de Contactos es una herramienta de consulta.** `/api/segments.preview` acepta cualquier definición, no solo un segmento guardado, así que la combinación puede contar contactos según cualquier condición sobre atributos, pertenencia a listas, eventos personalizados e historial, un recuento cada vez. La lectura de Segmentos sola no puede.
- **La lectura de Historial de mensajes da acceso a datos de contactos.** El registro contiene las direcciones de los destinatarios y los datos con los que se renderizó cada mensaje.
- **La escritura de LLM gasta.** Las peticiones al asistente de IA van a tu proveedor de IA configurado, se facturan a tu espacio de trabajo y no tienen límite por clave. Con una integración de Firecrawl configurada, también permite al asistente extraer contenido y buscar en la web con tus credenciales.

### Envíos transaccionales y contactos

**La escritura de Transaccional basta por sí sola para enviar**, así que una clave que solo envía es viable. Las reglas son las mismas por la API y por el [puente SMTP](https://www.notifuse.com/es/docs/features/transactional-api.md):

- **Sin la escritura de Contactos**, el envío sigue creando el contacto destinatario cuando no existe, pero no guarda nada más que la dirección de correo y nunca modifica un contacto existente.
- **Sin la lectura de Contactos**, se rechaza un envío que pone `cc` o `bcc`, porque el asunto se renderiza con el registro completo de cada destinatario. En el puente SMTP, estos vienen de las cabeceras `Cc:` y `Bcc:` del mensaje.

La escritura de Transaccional envía correo real desde dos endpoints, `/api/transactional.send` y `/api/transactional.testTemplate`, y desde el puente SMTP. Probar un proveedor de correo (`/api/email.testProvider`) está reservado al propietario del espacio de trabajo, igual que crear y editar integraciones, sean cuales sean los permisos de la clave. Un correo de prueba (`/api/transactional.testTemplate`) también necesita la lectura de Plantillas, ya que lee la plantilla con tus propios permisos, y la lectura de Listas cuando se envía para una lista de correo. Crear una notificación transaccional también necesita la lectura de Plantillas, igual que editar una con sus `channels`, que la consola envía al editar una notificación que no gestiona ninguna integración.
