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.
`contacts`	`read` · `create` · `update` · `delete`	Contactos: gestionar contactos y sus vínculos.
`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 y plantilla).
`inboxes`	`read` · `create` · `update`	Inboxes: gestionar inboxes.
`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.

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

Excepción conocida: DELETE /v1/inboxes/{id} exige el scope inboxes:delete, que no está en el catálogo del panel: una clave creada allí recibe 403 en este endpoint. Para concederlo, cree la clave por POST /v1/api-keys incluyendo "inboxes:delete" en scopes: la creación valida solo el formato <subject>:<action>, no el catálogo. Todos los demás scopes exigidos por los endpoints de la Referencia están en el catálogo.

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