Las API keys son credenciales que permiten que sistemas externos se autentiquen en la API de Nuvia en nombre de tu empresa. Cada clave tiene sus propios alcances de permiso y se puede revocar cuando quieras.
Disponible en: Todos los planes.
Quién puede hacerlo: Administradores de la cuenta.
Antes de empezar
-
Confirma que tu perfil tiene acceso de administrador.
-
Ten un lugar seguro para guardar el token, como un gestor de secretos. El token se muestra una sola vez, al momento de crearlo; después no hay forma de volver a verlo.
Acceder a la página de API Keys
-
En el Menú lateral, haz clic en los 3 puntos junto al ícono de perfil
-
Haz clic en la opción Configuración
-
En el Menú lateral, haz clic en API Keys
La lista muestra todas las API keys de tu empresa, con nombre, alcances, vista previa del token (los 4 últimos caracteres), fecha de creación, vencimiento, último uso y estado.
Crear una nueva API key
-
En la página de API Keys, haz clic en Nueva API Key.
-
Completa el Nombre; usa algo descriptivo que identifique la integración (ej.: “CRM Integration”, “Dashboard BI”).
-
Selecciona los Alcances a los que podrá acceder esta clave (mira la lista completa en la sección Alcances de permiso disponibles, más abajo).
-
(Opcional) Define un Vencimiento eligiendo una fecha futura en el calendario. Si lo dejas en blanco, la clave no vence.
-
Haz clic en Crear API Key.
-
Haz clic en Copiar token para copiar el JWT al portapapeles.
-
Guarda el token en un lugar seguro.
-
Haz clic en Cerrar.
Alcances de permiso disponibles
Cada alcance habilita un conjunto de acciones sobre un recurso de la API. Eliges los alcances al momento de crear la clave.
| Recursos | Acciones disponibles |
|---|---|
| Agentes | Leer, Crear, Actualizar, Eliminar |
| Contactos | Leer, Crear, Actualizar, Eliminar |
| Conversaciones | Leer, Crear, Actualizar |
| Campañas | Leer, Crear, Actualizar, Eliminar |
| Mensajes | Leer, Enviar |
| Bandejas de entrada | Leer, Crear, Actualizar, Eliminar |
| Tablas | Leer, Crear, Actualizar, Eliminar |
| Tools de agente | Leer, Crear, Actualizar, Eliminar |
| Seguimientos de agente | Leer, Crear, Actualizar, Eliminar |
| Notas de contacto | Leer, Crear, Actualizar |
| Inscripciones de campaña | Leer, Crear |
| Campos personalizados | Leer, Actualizar valor |
| Base de conocimiento | Leer, Crear, Actualizar |
| Webhooks | Leer, Crear, Actualizar, Eliminar |
| Búsqueda | Consultar, Enriquecer y guardar |
| Búsqueda LinkedIn | Consultar, Guardar |
| Enriquecimiento | Consultar, Ejecutar |
| Triggers de campaña | Disparar |
Qué habilitan los alcances de Campos personalizados
Los alcances de Campos personalizados sirven para que una integración guarde valores en campos que ya existen, no para crear o borrar la definición del campo.
| Alcance | Qué puede hacer la clave |
|---|---|
| Campos custom — Leer | Listar los campos personalizados de la empresa (para descubrir el identificador de cada uno) y listar las opciones activas de un campo de lista desplegable o de opción múltiple |
| Campos custom — Actualizar valor | Guardar el valor de un campo personalizado en una conversación, en su contacto o en la empresa del contacto |
Al guardar valores, ten en cuenta:
-
El campo se identifica por el slug (el identificador que aparece en la lista de campos), no por el ID interno.
-
La conversación es obligatoria en la llamada, incluso cuando el campo es de contacto o de empresa: a partir de la conversación Nuvia encuentra el contacto y la empresa.
-
Los campos de texto, número y fecha reciben el valor directamente. Los campos de lista desplegable y de opción múltiple reciben el identificador de la opción, que viene de la lista de opciones del campo.
-
Un valor fuera de las opciones aceptadas se rechaza, y la respuesta trae la lista de valores válidos.
-
Un campo o una conversación de otra empresa se rechaza.
Disparar campañas desde un CRM propio (alcance Triggers de campaña)
El alcance Triggers de campaña — Disparar habilita el endpoint que permite que un CRM propio o una automatización (n8n, Zapier o una llamada directa a la API) dispare campañas en Nuvia a partir de eventos de tu CRM: contacto creado o actualizado, negocio (deal) creado o actualizado y lead creado o actualizado.
Úsalo cuando tu CRM no es uno de los integrados de forma nativa (HubSpot o RD Station) y quieres que active campañas en Nuvia. La automatización envía el contacto (con teléfono) y los datos del evento, y Nuvia inscribe el contacto en las campañas configuradas.
Filtrar y buscar API keys
Usa los filtros en la esquina superior derecha de la página para alternar entre:
-
Activas: claves que pueden autenticar solicitudes (vista predeterminada).
-
Revocadas: claves desactivadas de forma permanente.
-
Todas: muestra activas y revocadas.
También puedes encontrar una clave por nombre con el campo de búsqueda.
Revocar una API key
La revocación desactiva la clave de forma permanente. Úsala cuando una integración se discontinúe, cuando vayas a rotar credenciales o cuando sospeches de una filtración.
-
En la lista, ubica la API key que quieres revocar.
-
Haz clic en el menú de acciones (⋮) a la derecha de la fila.
-
Haz clic en Revocar.
-
En el modal de confirmación, completa la Justificación (ej.: “integración discontinuada”, “key filtrada”, “rotación de credenciales”).
-
Haz clic en Revocar API Key.
-
La clave deja de autenticar solicitudes de inmediato.
Estado de una API key
| Estado | Color en la interfaz | Qué significa |
|---|---|---|
| Activa | Verde | La clave funciona y autentica solicitudes normalmente. |
| Vencida | Rojo | La fecha de vencimiento configurada ya pasó; la clave ya no autentica. Crea una nueva para continuar. |
| Revocada | Gris | Un usuario desactivó la clave de forma permanente y ya no autentica. |