Saltar a contenido

Autenticación

La API soporta dos mecanismos de autenticación. Para integraciones server-to-server (scripts, backends, automatizaciones) recomendamos API Key. El JWT de sesión existe para clientes de navegador.

API Key (mecanismo primario, server-to-server)

Cada request autenticada con API Key envía el header:

X-API-Key: nrn_live_<32 caracteres hex>

El formato real es el prefijo nrn_live_ seguido de 32 caracteres hexadecimales (41 caracteres en total). Ejemplo:

API_BASE_URL="https://api.neuronstudio.ai"

curl "$API_BASE_URL/api/campaigns" \
  -H "X-API-Key: nrn_live_abcdef1234567890abcdef1234567890"

La organización va implícita en la key: no existe header X-Tenant-ID. Una key solo ve y opera datos de su propia organización.

Scopes: read y full

Cada API Key tiene un scope que define qué puede hacer:

Scope Permite No permite
read Solo métodos GET (consultas, estado, analytics, listados). Cualquier POST / PATCH / DELETE → responde 403.
full Todo el ciclo: iniciar, detener, pausar, reanudar y programar campañas, más todas las lecturas. —

Regla práctica:

  • ¿Tu integración solo consulta resultados y estado? → pide una key con scope read.
  • ¿Tu integración también lanza o controla campañas? → necesitas scope full.

Un POST/DELETE con una key read devuelve 403 (scope insuficiente). Ver Errores y troubleshooting.

JWT de sesión (navegador)

Para clientes de sesión (apps web, herramientas internas), el login devuelve un token de acceso:

curl -X POST "$API_BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "usuario@empresa.com", "password": "tu_password"}'

{ "success": true, "access_token": "eyJhbGciOiJIUzI1NiI...", "user": { "...": "..." } }

El token se usa en las requests siguientes como:

Authorization: Bearer eyJhbGciOiJIUzI1NiI...

Las sesiones se renuevan solas mediante una cookie httpOnly, sin que tengas que volver a hacer login. (La renovación es transparente para clientes de navegador.)

Para integraciones server-to-server, usa API Key, no JWT. La API Key es más simple de manejar, no expira por sesión y se rota de forma independiente por integración.

Emisión de API Keys (admin + MFA)

La creación de API Keys no es self-serve:

  • Las keys las emite un administrador de tu organización.
  • La emisión y la revocación requieren verificación MFA.
  • Cada key se muestra una sola vez al crearla. Si la pierdes, hay que emitir una nueva.

👉 Para obtener, rotar o revocar una key, contacta a tu administrador de organización o a tu contacto de Neuron.

Buenas prácticas

  • No expongas la key en el frontend. La API Key es una credencial server-to-server. Nunca la incluyas en código de navegador, apps móviles ni repositorios públicos.
  • Una key por integración. Usa keys distintas para cada sistema/integración. Así puedes revocar una sin afectar a las demás, y los límites de uso se cuentan de forma independiente.
  • Aplica el mínimo scope necesario. Si una integración solo lee, dale scope read.
  • Rota las keys periódicamente y de inmediato si sospechas que una se filtró. La rotación se gestiona con tu administrador (requiere MFA).
  • Guarda las keys en un gestor de secretos o variable de entorno, nunca en texto plano en el código.

Ver también