Autenticacion
Autenticate con la API de Auralytik usando claves API y firma HMAC de solicitudes. Cada solicitud debe incluir una clave API valida en el encabezado X-Api-Key.
1. Autenticacion con Clave API
Las claves API se crean en el panel Admin > Claves API. Cada clave esta asociada a un cliente especifico y un conjunto de permisos. Incluye tu clave en el encabezado X-Api-Key en cada solicitud.
Incluye tu clave API en el encabezado X-Api-Key:
curl https://api.auralytik.ai/api/v1/evaluations \ -H "X-Api-Key: ak_live_abc123def456ghi789jkl012mno345pq" \ -H "Content-Type: application/json"
Formato de clave
Las claves de produccion usan el prefijo ak_live_ seguido de 32 caracteres alfanumericos.
Ejemplo: ak_live_abc123def456ghi789jkl012mno345pq
El secreto completo de la clave se muestra solo una vez
Cuando creas una clave, el secreto completo se muestra una sola vez. Copialo inmediatamente y guardalo en un vault seguro o variable de entorno. No se puede recuperar despues -- solo rotar. Nunca expongas claves en codigo del lado del cliente, repositorios Git o logs.
2. Firma HMAC de Solicitudes
Todas las solicitudes realizadas con claves ak_live_ deben incluir una firma HMAC-SHA256. Esto previene ataques de repeticion y asegura la integridad de la solicitud. Se requieren dos encabezados adicionales:
| Encabezado | Valor |
|---|---|
| X-Signature | Firma HMAC-SHA256 codificada en Base64 |
| X-Timestamp | Timestamp Unix actual en segundos |
Pasos de firma
Obtener el timestamp Unix actual (segundos desde epoch).
Hacer hash del cuerpo de la solicitud con SHA-256 y codificar el resultado en Base64. Para solicitudes sin cuerpo (GET, DELETE), usar el hash de una cadena vacia.
Construir la cadena canonica usando este formato:
{timestamp}.{METHOD}.{path}.{bodyHash}path es solo la ruta de la URL (ej. /api/v1/evaluations), sin query string ni host.
Firmar la cadena canonica con HMAC-SHA256 usando tu clave secreta HMAC, luego codificar el resultado en Base64. Enviar este valor en el encabezado X-Signature.
Pseudocodigo
timestamp = current_unix_seconds()
body_hash = base64(sha256(request_body)) # empty string if no body
canonical = f"{timestamp}.{method}.{path}.{body_hash}"
signature = base64(hmac_sha256(hmac_key, canonical))
# Send headers
X-Api-Key: ak_live_...
X-Timestamp: {timestamp}
X-Signature: {signature}Ejemplo con curl
# Variables API_KEY="ak_live_abc123def456ghi789jkl012mno345pq" HMAC_KEY="your-hmac-secret-key" TIMESTAMP=$(date +%s) BODY='' BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64) CANONICAL="$TIMESTAMP.GET./api/v1/evaluations.$BODY_HASH" SIGNATURE=$(echo -n "$CANONICAL" | openssl dgst -sha256 -hmac "$HMAC_KEY" -binary | base64) curl https://api.auralytik.ai/api/v1/evaluations \ -H "X-Api-Key: $API_KEY" \ -H "X-Timestamp: $TIMESTAMP" \ -H "X-Signature: $SIGNATURE" \ -H "Content-Type: application/json"
Los timestamps expiran despues de 5 minutos
El servidor rechaza cualquier solicitud donde X-Timestamp difiera del reloj del servidor por mas de 300 segundos. Mantiene tu reloj del sistema sincronizado con NTP.
3. Permisos y Alcances
Cada clave API tiene asignados uno o mas alcances que controlan a que endpoints puede acceder. Asigna los alcances minimos necesarios para tu integracion.
| Alcance | Descripcion |
|---|---|
| evaluations:read | Leer resultados y puntuaciones de evaluaciones |
| audio:read | Listar y ver metadatos de archivos de audio |
| audio:download | Descargar contenido de archivos de audio |
| audio:write | Subir y gestionar archivos de audio |
| engagements:read | Leer registros de engagements |
| engagements:write | Crear y actualizar engagements |
| conversations:read | Leer datos de conversaciones y mensajes |
| voice:read | Leer registros de llamadas de voz |
| analytics:read | Acceder a analytics y dashboards |
| analytics:export | Exportar datos de analytics (CSV, Excel) |
| campaigns:read | Leer configuraciones de campanas |
| webhooks:manage | Crear, actualizar y eliminar webhooks |
| keys:manage | Gestionar claves API (solo admin) |
| usage:read | Ver metricas de uso y facturacion de la API |
Principio de minimo privilegio
Solo otorga los alcances que tu integracion realmente necesita. Siempre puedes agregar mas alcances despues sin rotar la clave.
4. Limites de Tasa
Los limites de tasa se aplican por clave API. Cuando excedes un limite, la API responde con 429 Too Many Requests.
| Nivel | Solicitudes / min | Limite diario |
|---|---|---|
| Standard | 300 | 50,000 |
| Premium | 1,000 | 200,000 |
| Enterprise | 5,000 | 1,000,000 |
Encabezados de limite de tasa
| Encabezado | Descripcion |
|---|---|
| X-RateLimit-Limit | Maximo de solicitudes permitidas en la ventana actual |
| X-RateLimit-Remaining | Solicitudes restantes en la ventana actual |
| X-RateLimit-Reset | Timestamp Unix cuando la ventana se reinicia |
| X-RateLimit-RetryAfter | Segundos a esperar antes de reintentar (solo en respuestas 429) |
Implementa backoff exponencial
Cuando recibas una respuesta 429, espera la cantidad de segundos indicada por X-RateLimit-RetryAfter antes de reintentar. Combina con backoff exponencial para mejores resultados.
5. Lista Blanca de IPs
Opcionalmente puedes restringir cada clave API a un conjunto de direcciones IP o rangos CIDR permitidos. Las solicitudes desde cualquier otra IP seran rechazadas con 403 Forbidden.
Ejemplo: restringir una clave a dos IPs y un bloque CIDR
{
"allowed_ips": [
"203.0.113.10",
"198.51.100.25",
"10.0.0.0/16"
]
}La lista blanca de IPs es opcional
Si no se configuran IPs, la clave funciona desde cualquier direccion. Recomendamos habilitar la lista blanca para claves de produccion para reducir el impacto de un secreto comprometido.
6. Rotacion de Claves
Rota una clave para generar un nuevo secreto sin cambiar el ID de la clave, los alcances ni las restricciones de IP. Durante el periodo de gracia de 24 horas, tanto el secreto antiguo como el nuevo son aceptados, dandote tiempo para actualizar todos los consumidores.
Rotar una clave via la API:
POST https://api.auralytik.ai/api/v1/api-keys/{id}/rotate
# Response
{
"id": "key_abc123",
"new_secret": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"hmac_key": "new-hmac-secret-key",
"old_secret_expires_at": "2026-03-31T14:30:00Z",
"grace_period_hours": 24
}Requiere el alcance keys:manage
La clave API utilizada para llamar al endpoint de rotacion debe tener el alcance keys:manage. Recomendamos usar una clave de administrador separada para operaciones de gestion de claves.
Mejor practica de rotacion
Rota las claves en un calendario regular (ej. cada 90 dias) e inmediatamente despues de cualquier sospecha de compromiso. El periodo de gracia de 24 horas asegura rotacion sin tiempo de inactividad para sistemas distribuidos.