Autenticación¶

La API admite dos mecanismos de autenticación: API Key (recomendado para integraciones server-to-server) y JWT (sesión de navegador). La organización va siempre implícita en la credencial — no existe un header de tenant.

Base URL: https://api.neuronstudio.ai

API Key (recomendado para server-to-server)¶

• Header: X-API-Key: nrn_live_<32 hex> (formato: prefijo nrn_live_ + 32 caracteres hexadecimales = 41 caracteres).
• La key lleva un scope:
• read → solo métodos GET.
• full → todo el ciclo de campañas + todas las lecturas.
• La organización va implícita en la key. Una key solo ve datos de su propia organización. No existe el header X-Tenant-ID.

Ejemplo de uso en cualquier endpoint:

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

curl -s "$API_BASE_URL/api/agents" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef"

Cómo obtener una API Key¶

La emisión de API Keys no es self-serve. Las keys las crea un administrador de tu organización (con MFA) y se muestran una sola vez. Solicita tu API Key a tu contacto de Neuron o al administrador de tu organización.

Para integraciones server-to-server prefiere API Key sobre JWT: no expira en 24 horas, no requiere refrescar sesión y lleva el scope acotado.

POST /api/auth/login¶

Inicia sesión con email y password y devuelve un access_token (JWT). Pensado para sesiones de navegador. Para integraciones server-to-server, usa API Key.

Body (JSON)¶

Ejemplo de request¶

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

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

Ejemplo de response (200)¶

{
  "success": true,
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 123,
    "email": "usuario@tuempresa.com",
    "name": "Juan Pérez",
    "role": "admin",
    "organization_id": 1,
    "organization_name": "Tu Empresa S.A."
  }
}

Usar el token¶

Guarda el access_token y envíalo en el header Authorization de las siguientes solicitudes:

curl -s "$API_BASE_URL/api/campaign/status" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

La sesión de navegador se renueva automáticamente vía cookie httpOnly.

Códigos de error¶

Forma del error:

{
  "success": false,
  "error": "Credenciales inválidas",
  "error_id": "3f2b1a90-...",
  "request_id": "9c7d4e21-..."
}

API Key vs JWT — cuándo usar cada uno¶

Para automatizar campañas desde tu backend, usa API Key con scope full.