Autenticación

Toda solicitud a la API de Nuvia se autentica con un token Bearer enviado en el header Authorization. Esta página explica cómo autenticar llamadas con una API key que usted ya posee. Para generar, listar y revocar claves, consulte la Guía de API key.

Base URL

https://api.nuvia.ai

Todas las rutas de la API REST usan el prefijo de versión /v1. Por ejemplo, listar agentes es GET https://api.nuvia.ai/v1/agents.

La API key de Nuvia no usa un header X-API-Key ni un token en el formato sk_.... La clave se envía como un token Bearer en el header Authorization:

Authorization: Bearer <su-api-key>

Enviar la clave en X-API-Key resulta en 401, porque el servidor no lee ese header.

Dos formas de autenticar

La API acepta dos tipos de identidad en el mismo header Authorization: Bearer:

API key de empresa: es lo que usa para integración programática. La clave está vinculada a su empresa y a los scopes definidos en la creación; puede tener validez opcional (expiresAt). Es el método recomendado para servidores, scripts e integraciones.
JWT humano: el token de sesión emitido por el flujo de inicio de sesión de la aplicación (POST /v1/auth/login). Representa a un usuario humano, no una integración. No lo necesita para consumir la API vía API key. Los endpoints de inicio de sesión pertenecen a la plataforma y no aparecen en la Referencia de la API, que cubre la superficie consumible por API key.

El servidor identifica automáticamente cuál de los dos fue enviado por el propio contenido del token. El tipo no se indica en ningún lugar. Para el resto de esta documentación, se asume el uso de API key de empresa.

Autenticando una solicitud

Incluya el header Authorization en cada llamada. El siguiente ejemplo lista los agentes de su empresa (requiere el scope agents:read):

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

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

const data = await res.json();

import os
import requests

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

data = res.json()

La API key es un token de acceso completo al scope concedido. Trátela como un secreto: 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.

Multi-tenant y el header `X-Company-Id`

El tenant (empresa) de una API key de empresa se resuelve por el propio token. No necesita indicarlo. El header X-Company-Id solo es obligatorio para claves globales de uso interno y se ignora para API keys de empresa y para JWT humano. En resumen: integrando con una API key de empresa, no envía X-Company-Id.

Errores de autenticación

Las respuestas de error de autenticación siguen el formato { statusCode, message, error }.

401: no autenticado

Se retorna cuando el token está ausente, es inválido, expiró o fue revocado.

{
  "statusCode": 401,
  "message": "Autenticación inválida",
  "error": "Unauthorized"
}

El campo message detalla la causa cuando es posible, por ejemplo "API key inválida", "API key expirada", "API key revocada" o "API key no encontrada".

403: sin permiso

Se retorna cuando el token es válido, pero la API key no tiene el scope necesario para la acción, o el endpoint no está disponible para API keys.

{
  "statusCode": 403,
  "message": "API key no posee el scope necesario para esta acción",
  "error": "Forbidden"
}

Si recibe 403 en una llamada que debería funcionar, verifique si la clave fue creada con el scope exigido por el endpoint. Los scopes se definen en el momento de la creación de la clave. Consulte la Guía de API key.

Primeros pasos

Guías

Base URL

Dos formas de autenticar

Autenticando una solicitud

Multi-tenant y el header `X-Company-Id`

Errores de autenticación

401: no autenticado

403: sin permiso

Próximos pasos

Guía de API key

Inicio rápido

​Base URL

​Dos formas de autenticar

​Autenticando una solicitud

​Multi-tenant y el header X-Company-Id

​Errores de autenticación

​401: no autenticado

​403: sin permiso

​Próximos pasos

Guía de API key

Inicio rápido

Base URL

Dos formas de autenticar

Autenticando una solicitud

Multi-tenant y el header `X-Company-Id`

Errores de autenticación

401: no autenticado

403: sin permiso

Próximos pasos