Descripción General
Neuracall utiliza OAuth2 con Auth0 para autenticación. Todos los endpoints (excepto /v1/auth) requieren un token de acceso valido.
Flujo de Autenticación
Obtener Credenciales
Para usar la API necesitas:
| Credencial | Descripción |
|---|
client_id | Identificador único de tu aplicación |
client_secret | Clave secreta (mantener segura) |
Obtener Token de Acceso
curl -X POST https://api.neuracall.com/v1/auth \
-H "Content-Type: application/json" \
-d '{
"client_id": "nc_client_a1b2c3d4e5f6g7h8",
"client_secret": "nc_secret_x9y8z7w6v5u4t3s2"
}'
import requests
response = requests.post(
"https://api.neuracall.com/v1/auth",
json={
"client_id": "nc_client_a1b2c3d4e5f6g7h8",
"client_secret": "nc_secret_x9y8z7w6v5u4t3s2"
}
)
data = response.json()
token = data["access_token"]
expires_at = data["expires_at"]
const response = await fetch("https://api.neuracall.com/v1/auth", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: "nc_client_a1b2c3d4e5f6g7h8",
client_secret: "nc_secret_x9y8z7w6v5u4t3s2"
})
});
const { access_token, expires_at } = await response.json();
Respuesta
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_at": 1735689600,
"client_id_audience": "https://api.neuracall.com/call-analysis",
"scope": "read:call-analysis-requests write:call-analysis-request read:call-analysis-audio read:call-analysis-transcription read:prompt-template write:prompt-template read:call-analysis-stats"
}
Usar el Token
Incluye el token en el header Authorization de cada solicitud:
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
curl https://api.neuracall.com/v1/call-analysis \
-H "Authorization: Bearer TU_ACCESS_TOKEN"
response = requests.get(
"https://api.neuracall.com/v1/call-analysis",
headers={"Authorization": f"Bearer {token}"}
)
const response = await fetch("https://api.neuracall.com/v1/call-analysis", {
headers: { "Authorization": `Bearer ${access_token}` }
});
Scopes (Permisos)
Los tokens incluyen scopes que determinan que operaciónes puede realizar tu aplicación:
| Scope | Descripción |
|---|
read:call-analysis-requests | Listar y ver análisis de llamadas |
write:call-analysis-request | Crear nuevos análisis |
read:call-analysis-audio | Descargar archivos de audio |
read:call-analysis-transcription | Ver transcripciónes |
read:prompt-template | Ver modelos de análisis |
write:prompt-template | Crear y editar modelos |
read:call-analysis-stats | Acceder a estadísticas |
Manejo de Expiracion
Los tokens tienen una duración limitada. El campo expires_at indica el timestamp Unix de expiración.
Recomendacion: Renueva el token antes de que expire para evitar interrupciones.
Python - Renovacion automática
import time
class NeuracallClient:
def __init__(self, client_id, client_secret):
self.client_id = client_id
self.client_secret = client_secret
self.token = None
self.expires_at = 0
def get_token(self):
# Renovar si expira en menos de 5 minutos
if time.time() > self.expires_at - 300:
response = requests.post(
"https://api.neuracall.com/v1/auth",
json={
"client_id": self.client_id,
"client_secret": self.client_secret
}
)
data = response.json()
self.token = data["access_token"]
self.expires_at = data["expires_at"]
return self.token
Errores de Autenticación
| Código | Descripción | Solucion |
|---|
| 401 | Credenciales invalidas | Verifica client_id y client_secret |
| 401 | Token expirado | Solicita un nuevo token |
| 401 | Token invalido | Verifica el formato del header Authorization |
| 403 | Scope insuficiente | Contacta soporte para ampliar permisos |
Ejemplo de error
{
"code": "001-001-0001",
"message": "Invalid credentials"
}
Seguridad
Nunca expongas tus credenciales en código del lado del cliente, repositorios publicos o logs.
Mejores practicas
- Almacena credenciales en variables de entorno
- Usa un gestor de secretos en produccion
- Rota las credenciales periodicamente
- Monitorea el uso de la API por actividad sospechosa
Ejemplo con variables de entorno
export NEURACALL_CLIENT_ID="nc_client_..."
export NEURACALL_CLIENT_SECRET="nc_secret_..."
import os
client_id = os.environ["NEURACALL_CLIENT_ID"]
client_secret = os.environ["NEURACALL_CLIENT_SECRET"]
