Guía de API key

Una API key es el token que su integración usa para autenticarse en la API de Nuvia. Para saber cómo enviar la clave en las solicitudes, consulte Autenticación. Esta página cubre el ciclo de vida de la clave: crear, listar, revocar y elegir scopes.

Las API keys se crean y gestionan desde un usuario humano autenticado con el token de inicio de sesión de la aplicación (JWT humano, ver Autenticación). Una API key no gestiona otras API keys: los endpoints de /v1/api-keys no aceptan autenticación por API key.

Crear una API key

Envíe un POST /v1/api-keys autenticado como usuario. El cuerpo acepta:

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre de identificación de la clave (hasta 100 caracteres).
`scopes`	string[]	Sí	Lista de scopes en formato `<subject>:<action>` (ver el catálogo abajo).
`expiresAt`	string (ISO 8601)	No	Fecha futura de expiración. Si se omite, la clave no expira por tiempo.

curl -X POST https://api.nuvia.ai/v1/api-keys \
  -H "Authorization: Bearer $NUVIA_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integración de producción",
    "scopes": ["contacts:read", "messages:create"],
    "expiresAt": "2027-01-01T00:00:00.000Z"
  }'

const res = await fetch("https://api.nuvia.ai/v1/api-keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUVIA_USER_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Integración de producción",
    scopes: ["contacts:read", "messages:create"],
    expiresAt: "2027-01-01T00:00:00.000Z",
  }),
});

const { accessToken, apiKey } = await res.json();

import os
import requests

res = requests.post(
    "https://api.nuvia.ai/v1/api-keys",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_USER_TOKEN']}"},
    json={
        "name": "Integración de producción",
        "scopes": ["contacts:read", "messages:create"],
        "expiresAt": "2027-01-01T00:00:00.000Z",
    },
)

body = res.json()
access_token = body["accessToken"]

La respuesta (201) trae el token en accessToken y los metadatos de la clave en apiKey:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "apiKey": {
    "name": "Integración de producción",
    "scopes": ["contacts:read", "messages:create"],
    "status": "ACTIVE",
    "keyPreview": "...a1b2",
    "expiresAt": "2027-01-01T00:00:00.000Z"
  }
}

El valor completo del token aparece una sola vez, en el campo accessToken de la respuesta de creación. Nuvia no almacena el token y no hay forma de recuperarlo después: solo quedan guardados los metadatos y una vista previa (keyPreview, los últimos 4 caracteres). Copie y guarde el token de forma segura en ese momento. Si pierde el token, revoque la clave y cree una nueva.

Listar API keys

GET /v1/api-keys devuelve las claves de su empresa (con paginación { data, meta }). La respuesta solo trae metadatos, nunca el token.

curl https://api.nuvia.ai/v1/api-keys \
  -H "Authorization: Bearer $NUVIA_USER_TOKEN"

const res = await fetch("https://api.nuvia.ai/v1/api-keys", {
  headers: { Authorization: `Bearer ${process.env.NUVIA_USER_TOKEN}` },
});

const { data, meta } = await res.json();

import os
import requests

res = requests.get(
    "https://api.nuvia.ai/v1/api-keys",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_USER_TOKEN']}"},
)

data = res.json()["data"]

Revocar una API key

DELETE /v1/api-keys/:id revoca la clave de inmediato y responde 204 No Content. La operación es idempotente: revocar una clave ya revocada no genera error. La clave debe pertenecer a su empresa.

cURL

curl -X DELETE https://api.nuvia.ai/v1/api-keys/652f1a9c8b3e4d0012a7f4c1 \
  -H "Authorization: Bearer $NUVIA_USER_TOKEN"

Una vez revocada, la clave deja de autenticar en cualquier solicitud.

Scopes disponibles

Los scopes siguen el formato <subject>:<action>. Al crear una clave, conceda solo los scopes que la integración necesita. La siguiente tabla lista el catálogo disponible en el panel, agrupado por subject.

Subject	Acciones	Qué habilita el subject
`agents`	`read` · `create` · `update` · `delete`	Agentes de IA: listar, crear, clonar y actualizar.
`agent-tools`	`read` · `create` · `update` · `delete`	Herramientas de agente: las tools (HTTP o MCP) que llaman los agentes de IA. Listar, crear, actualizar, probar y eliminar. Aún sin página en la Referencia.
`agent-followups`	`read` · `create` · `update` · `delete`	Follow-ups de agente: la cadencia de follow-up que la plataforma envía por sí sola a los leads. Aún sin página en la Referencia.
`contacts`	`read` · `create` · `update` · `delete`	Contactos: gestionar contactos y sus vínculos.
`contact-notes`	`read` · `create` · `update` · `delete`	Notas de contacto: listar, crear, actualizar y eliminar las notas de un contacto. Aún sin página en la Referencia.
`custom-fields`	`read` · `update`	Campos personalizados: listar los campos y las opciones de `select`/`multi_select` y escribir el valor de un campo en la conversación, el contacto o la empresa. Crear o editar la definición de un campo solo es posible en la pantalla.
`conversations`	`read` · `create` · `update`	Conversaciones: listar y actualizar (asignar agente, propietario, prioridad, equipo).
`campaigns`	`read` · `create` · `update` · `delete`	Campañas: gestionar campañas, activación y analytics.
`campaign-enrollments`	`read` · `create`	Inscripciones a campaña: inscribir contactos (individual, por lista, embudo o `contact_ids`) y listar inscripciones.
`triggers`	`create`	Disparadores de campaña: activar la inscripción por evento.
`messages`	`read` · `create`	Mensajes: leer mensajes y adjuntos de una conversación y enviar texto, plantillas y archivos.
`inboxes`	`read` · `create` · `update` · `delete`	Inboxes: gestionar inboxes.
`inbox-snippets`	`read` · `create` · `update` · `delete`	Respuestas rápidas: listar, crear, duplicar, actualizar y eliminar, y completar las variables de una respuesta para una conversación. Aún sin página en la Referencia.
`tables`	`read` · `create` · `update` · `delete`	Tablas y listas: gestionar tablas, columnas y exportaciones.
`knowledge-base`	`read` · `create` · `update`	Base de conocimiento: gestionar elementos de conocimiento.
`webhooks`	`read` · `create` · `update` · `delete`	Webhooks: gestionar configuraciones de webhook.
`search-v2`	`read` · `create`	Búsqueda de empresas y prospectos (Brasil y global) y autocompletado.
`linkedin-search`	`read` · `create`	Búsqueda en LinkedIn: perfiles, empresas y parámetros.
`enrichment`	`read` · `create`	Enriquecimiento de contactos y consulta de elegibilidad/créditos.
`hubspot`	`read`	HubSpot: leer la configuración de la integración (owners, mapeos, propiedades, pipelines, teléfono, sincronización e historial). Solo lectura.

hubspot:read aparece en el panel como HubSpot — Leer configuración, en el grupo HubSpot. Habilita las 10 lecturas de /v1/hubspot de la Referencia. Es solo lectura: cualquier cambio en la configuración de la integración con una API key devuelve 403, incluso con este scope. Los mapeos y la configuración se siguen editando en la pantalla de integración.Una clave ya creada no obtiene el scope, y no es posible editar los scopes de una clave existente. Para usar hubspot:read, genere una clave nueva con ese scope marcado.

El panel solo ofrece los scopes de este catálogo, y todo endpoint de la Referencia exige uno de ellos. Si un endpoint devuelve 403 incluso con una clave válida, confirme que la clave se creó con el scope que ese endpoint exige.

Modelo de propiedad

Una API key pertenece a la empresa (el tenant), no al usuario que la creó. El usuario creador queda registrado solo para auditoría. Una consecuencia importante:

La clave no se revoca automáticamente cuando el usuario que la creó es desactivado o eliminado de la empresa. Sigue siendo válida. Para terminar el acceso de una clave, revóquela explícitamente con DELETE /v1/api-keys/:id.

Buenas prácticas de seguridad

Trate la clave como un secreto

La API key es un Bearer token que da acceso a todo lo que sus scopes permiten. Guárdela en una variable de entorno o en un gestor de secretos, nunca en el código fuente ni en el control de versiones.

Aplique el mínimo privilegio

Conceda solo los scopes necesarios para la integración. Evite crear claves con el catálogo completo “por precaución”.

Defina una expiración

Use expiresAt para claves de vida corta o temporales, reduciendo la ventana de exposición si la clave se filtra.

Revoque lo que no use

Revoque claves antiguas, de pruebas o sin uso. Como la clave sobrevive a la salida del usuario creador, la limpieza es responsabilidad de la empresa.

Próximos pasos

Autenticación

Cómo enviar la API key en las solicitudes y entender los errores de autenticación.

Límites de uso

Cómo la API gestiona hoy los límites de solicitud.

Primeros pasos

Guías

Crear una API key

Listar API keys

Revocar una API key

Scopes disponibles

Modelo de propiedad

Buenas prácticas de seguridad

Próximos pasos

Autenticación

Límites de uso

​Crear una API key

​Listar API keys

​Revocar una API key

​Scopes disponibles

​Modelo de propiedad

​Buenas prácticas de seguridad

​Próximos pasos

Autenticación

Límites de uso

Crear una API key

Listar API keys

Revocar una API key

Scopes disponibles

Modelo de propiedad

Buenas prácticas de seguridad

Próximos pasos