API de Registros de Auditoría

Auris registra automáticamente cada acción administrativa, evento de autenticación y operación relevante para la seguridad en una pista de auditoría inmutable. La API de Registros de Auditoría proporciona acceso de lectura a estos registros y gestión de configuraciones de transmisión de logs que reenvían eventos a plataformas de observabilidad externas.

Los registros de auditoría se conservan según la política de retención de tu plan. Todas las entradas de registro son inmutables — no pueden editarse ni eliminarse a través de la API.

Todos los endpoints requieren el encabezado x-tenant y un Bearer Token válido.

Consultar Registros

GET/api/audit-logsRequires: view:audit_logs

Lista las entradas de registros de auditoría con filtrado y paginación. Los resultados se devuelven en orden cronológico inverso (más recientes primero). Soporta filtrado por acción, usuario, tipo de recurso, nivel de gravedad, rango de fechas y búsqueda de texto libre.

Parámetros de consulta

Parámetro	Tipo	Descripción
`page`	integer	Número de página (por defecto: 1)
`limit`	integer	Elementos por página (por defecto: 20, máx: 100)
`action`	string	Filtrar por nombre de acción (p. ej., `user.login`, `role.update`, `sso.connection.create`)
`userId`	string	Filtrar por el ID del usuario que realizó la acción
`resourceType`	string	Filtrar por tipo de recurso (p. ej., `user`, `role`, `application`, `organization`, `sso_connection`)
`level`	`info` \| `warn` \| `error`	Filtrar por nivel de gravedad del registro
`dateFrom`	ISO 8601	Inicio del rango de fechas (inclusivo)
`dateTo`	ISO 8601	Fin del rango de fechas (inclusivo)
`search`	string	Búsqueda de texto libre en acción, tipo de recurso y detalles

Ejemplo de solicitud


GET /api/audit-logs?action=user.login&level=error&dateFrom=2025-02-01T00:00:00Z&limit=50

Respuesta exitosa


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "log_abc123",
        "action": "user.login",
        "userId": "usr_def456",
        "resourceType": "session",
        "resourceId": "sess_ghi789",
        "details": {
          "method": "password",
          "success": false,
          "reason": "invalid_credentials"
        },
        "level": "error",
        "ipAddress": "203.0.113.42",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "createdAt": "2025-02-18T14:30:00Z"
      },
      {
        "id": "log_jkl012",
        "action": "role.update",
        "userId": "usr_admin001",
        "resourceType": "role",
        "resourceId": "role_mno345",
        "details": {
          "before": { "name": "editor", "permissionsChanged": 3 },
          "after": { "name": "editor", "permissionsChanged": 3, "permissions": ["view:invoices", "create:invoices", "edit:invoices"] }
        },
        "level": "info",
        "ipAddress": "10.0.1.50",
        "userAgent": "AurisConsole/1.0",
        "createdAt": "2025-02-18T13:15:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1284,
      "totalPages": 26
    }
  }
}

Estructura de una Entrada de Registro

Cada entrada de registro de auditoría tiene la siguiente estructura:

Campo	Tipo	Descripción
`id`	string	Identificador único de la entrada de registro
`action`	string	La acción realizada (notación de puntos, p. ej., `user.create`, `role.permission.update`)
`userId`	string \| null	El usuario que realizó la acción. Null para eventos generados por el sistema (cron jobs, webhooks).
`resourceType`	string	El tipo de recurso afectado (p. ej., `user`, `role`, `application`, `organization`, `session`, `sso_connection`, `log_stream`)
`resourceId`	string \| null	El ID del recurso específico afectado
`details`	object	Datos específicos de la acción. Para mutaciones, típicamente incluye instantáneas `before` y `after`.
`level`	`info` \| `warn` \| `error`	Nivel de gravedad del evento
`ipAddress`	string \| null	Dirección IP del cliente que desencadenó la acción
`userAgent`	string \| null	Encabezado User-Agent de la solicitud
`createdAt`	ISO 8601	Marca de tiempo de cuándo ocurrió el evento

Tipos de Acción Comunes

Acción	Nivel	Descripción
`user.login`	info/error	Intento de login de usuario (éxito o fallo)
`user.login.2fa`	info	Autenticación de dos factores completada
`user.signup`	info	Registro de nuevo usuario
`user.create`	info	Administrador creó un usuario
`user.update`	info	Perfil de usuario actualizado
`user.delete`	warn	Cuenta de usuario eliminada
`user.disable`	warn	Cuenta de usuario deshabilitada
`user.password.change`	info	Contraseña cambiada
`user.password.reset`	info	Restablecimiento de contraseña iniciado
`role.create`	info	Rol creado
`role.update`	info	Metadatos del rol actualizados
`role.delete`	warn	Rol eliminado
`role.permission.update`	info	Permisos del rol modificados
`role.assign`	info	Rol asignado a un usuario
`role.unassign`	info	Rol eliminado de un usuario
`application.create`	info	Aplicación creada
`application.update`	info	Configuración de la aplicación actualizada
`application.secret.rotate`	warn	Client secret de la aplicación rotado
`organization.create`	info	Organización creada
`organization.member.add`	info	Miembro añadido a la organización
`organization.member.remove`	warn	Miembro eliminado de la organización
`sso.connection.create`	info	Conexión SSO configurada
`sso.connection.activate`	info	Conexión SSO activada
`sso.connection.deactivate`	warn	Conexión SSO desactivada
`session.revoke`	warn	Administrador revocó una sesión de usuario
`token.exchange`	warn	Intercambio de token (suplantación o delegación)
`log_stream.create`	info	Transmisión de logs configurada
`security.brute_force.lockout`	error	Cuenta bloqueada por fuerza bruta
`security.suspicious_login`	warn	Login sospechoso detectado

El campo details para eventos de mutación (crear, actualizar, eliminar) típicamente incluye instantáneas before y after donde corresponde. Para campos sensibles como contraseñas y secretos, solo se registra el hecho de que el campo cambió, no los valores reales.

Transmisión de Logs

La transmisión de logs reenvía eventos de auditoría en tiempo real a plataformas de observabilidad y SIEM externas. Cuando una transmisión de logs está configurada y activa, cada evento de auditoría se envía al destino configurado además de almacenarse en la base de datos de Auris.

GET/api/log-streamsRequires: manage:log_streams

Lista todas las transmisiones de logs configuradas para el tenant. Devuelve metadatos de la transmisión, tipo, estado y hora de última entrega.

Respuesta exitosa


{
  "ok": true,
  "data": [
    {
      "id": "ls_abc123",
      "name": "Production Datadog",
      "type": "DATADOG",
      "status": "active",
      "config": {
        "region": "us1",
        "apiKey": "dd_api_***...***"
      },
      "lastDeliveryAt": "2025-02-18T14:29:55Z",
      "createdAt": "2025-01-10T09:00:00Z"
    },
    {
      "id": "ls_def456",
      "name": "SIEM Webhook",
      "type": "WEBHOOK",
      "status": "active",
      "config": {
        "url": "https://siem.internal.acme.com/auris-logs",
        "headers": { "X-Custom-Header": "value" }
      },
      "lastDeliveryAt": "2025-02-18T14:29:58Z",
      "createdAt": "2025-02-01T11:30:00Z"
    }
  ]
}

POST/api/log-streamsRequires: manage:log_streams

Crea una nueva transmisión de logs. Cada tipo de transmisión requiere una forma de configuración diferente. Auris valida la configuración y opcionalmente realiza una entrega de prueba antes de guardar.

Tipo de Transmisión: WEBHOOK

Envía cada evento de auditoría como un HTTP POST a la URL especificada. Soporta encabezados personalizados para autenticación.

Cuerpo de la solicitud


{
  "name": "SIEM Webhook",
  "type": "WEBHOOK",
  "config": {
    "url": "https://siem.internal.acme.com/auris-logs",
    "headers": {
      "Authorization": "Bearer your-siem-token",
      "X-Source": "auris"
    }
  }
}

Campo de Config	Requerido	Descripción
`url`	Sí	Endpoint HTTPS para recibir eventos de registro
`headers`	No	Encabezados HTTP personalizados enviados con cada entrega

El payload del webhook es la entrada de registro de auditoría en JSON, enviada con Content-Type: application/json.

Tipo de Transmisión: S3

Agrupa eventos de auditoría y los sube como archivos JSON a un bucket compatible con S3.

Cuerpo de la solicitud


{
  "name": "S3 Archive",
  "type": "S3",
  "config": {
    "bucket": "auris-audit-logs",
    "region": "us-east-1",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "prefix": "auris/tenant-name/"
  }
}

Campo de Config	Requerido	Descripción
`bucket`	Sí	Nombre del bucket S3
`region`	Sí	Región de AWS (p. ej., `us-east-1`)
`accessKeyId`	Sí	ID de clave de acceso de AWS con permiso `s3:PutObject`
`secretAccessKey`	Sí	Clave de acceso secreta de AWS
`prefix`	No	Prefijo de clave para los archivos subidos (por defecto: `auris-logs/`)

Los archivos se suben con claves en el formato: {prefix}YYYY/MM/DD/HH-mm-ss-{uuid}.json.

Tipo de Transmisión: DATADOG

Envía eventos de auditoría a la API de Gestión de Logs de Datadog.

Cuerpo de la solicitud


{
  "name": "Datadog Logs",
  "type": "DATADOG",
  "config": {
    "apiKey": "dd_api_key_here",
    "region": "us1",
    "service": "auris-iam",
    "source": "auris"
  }
}

Campo de Config	Requerido	Descripción
`apiKey`	Sí	Clave API de Datadog
`region`	Sí	Región de Datadog: `us1`, `us3`, `us5`, `eu1`, `ap1`
`service`	No	Etiqueta de nombre de servicio (por defecto: `auris`)
`source`	No	Etiqueta de fuente (por defecto: `auris`)

Tipo de Transmisión: SPLUNK

Envía eventos de auditoría a Splunk a través del Colector de Eventos HTTP (HEC).

Cuerpo de la solicitud


{
  "name": "Splunk HEC",
  "type": "SPLUNK",
  "config": {
    "hecUrl": "https://splunk.internal.acme.com:8088/services/collector/event",
    "hecToken": "your-hec-token",
    "index": "auris_audit",
    "source": "auris-iam",
    "sourcetype": "_json"
  }
}

Campo de Config	Requerido	Descripción
`hecUrl`	Sí	URL del endpoint HEC de Splunk
`hecToken`	Sí	Token de autenticación HEC
`index`	No	Índice de Splunk (por defecto: `main`)
`source`	No	Valor de fuente (por defecto: `auris`)
`sourcetype`	No	Valor de tipo de fuente (por defecto: `_json`)

Respuesta exitosa (todos los tipos)


{
  "ok": true,
  "data": {
    "id": "ls_ghi789",
    "name": "Datadog Logs",
    "type": "DATADOG",
    "status": "active",
    "config": {
      "region": "us1",
      "apiKey": "dd_api_***...***",
      "service": "auris-iam",
      "source": "auris"
    },
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Los campos sensibles de la configuración (claves API, secretos, tokens) se enmascaran en las respuestas GET. Los valores completos solo se usan internamente para la entrega y nunca se exponen a través de la API después de la creación.

Códigos de error

Código	HTTP	Descripción
`VALIDATION_ERROR`	400	Faltan campos de configuración requeridos o el tipo de transmisión es inválido
`STREAM_NAME_TAKEN`	409	Ya existe una transmisión de logs con este nombre
`TEST_DELIVERY_FAILED`	400	La entrega de prueba al endpoint configurado falló (se devuelve cuando el endpoint no es accesible o rechaza el evento de prueba)

GET/api/log-streams/[id]Requires: manage:log_streams

Obtiene los detalles completos de una transmisión de logs específica, incluyendo su configuración (con secretos enmascarados), estado y estadísticas de entrega.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "ls_abc123",
    "name": "Production Datadog",
    "type": "DATADOG",
    "status": "active",
    "config": {
      "region": "us1",
      "apiKey": "dd_api_***...***",
      "service": "auris-iam",
      "source": "auris"
    },
    "lastDeliveryAt": "2025-02-18T14:29:55Z",
    "deliveryCount": 15420,
    "errorCount": 3,
    "lastError": null,
    "createdAt": "2025-01-10T09:00:00Z",
    "updatedAt": "2025-02-15T08:00:00Z"
  }
}

PATCH/api/log-streams/[id]Requires: manage:log_streams

Actualiza el nombre, la configuración o el estado de una transmisión de logs. Úsalo para rotar claves API, cambiar endpoints o pausar/reanudar la transmisión.

Cuerpo de la solicitud — actualizar config


{
  "name": "Production Datadog (v2)",
  "config": {
    "apiKey": "new_dd_api_key_here"
  }
}

Cuerpo de la solicitud — pausar transmisión


{
  "status": "paused"
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "ls_abc123",
    "name": "Production Datadog (v2)",
    "status": "active",
    "updatedAt": "2025-02-18T11:00:00Z"
  }
}

Estados de la transmisión:

Estado	Descripción
`active`	Transmitiendo eventos al destino
`paused`	La transmisión está pausada — los eventos no se entregan pero siguen registrándose en Auris
`error`	La entrega ha fallado repetidamente — la transmisión se pausa automáticamente hasta que se corrija la configuración

DELETE/api/log-streams/[id]Requires: manage:log_streams

Elimina una transmisión de logs. La entrega se detiene inmediatamente. Los registros de auditoría históricos no se ven afectados — permanecen en la base de datos de Auris independientemente de la configuración de transmisión.

Respuesta exitosa


{
  "ok": true,
  "data": { "deleted": true }
}

Referencia de Permisos

Permiso	Descripción
`view:audit_logs`	Consultar y leer entradas de registros de auditoría
`manage:log_streams`	Crear, actualizar, eliminar y configurar destinos de transmisión de logs

Los registros de auditoría son de solo adición e inmutables. No existe un endpoint de API para eliminar o modificar entradas de registro. Esto garantiza la integridad de la pista de auditoría para fines de cumplimiento (SOC 2, ISO 27001, GDPR Artículo 30).

Formato de Entrega por Webhook

Para las transmisiones de logs de tipo WEBHOOK, cada evento se entrega como un HTTP POST con la siguiente estructura:


{
  "event": "audit_log",
  "timestamp": "2025-02-18T14:30:00Z",
  "tenant": "acme-corp",
  "data": {
    "id": "log_abc123",
    "action": "user.login",
    "userId": "usr_def456",
    "resourceType": "session",
    "resourceId": "sess_ghi789",
    "details": { "method": "password", "success": true },
    "level": "info",
    "ipAddress": "203.0.113.42",
    "userAgent": "Mozilla/5.0...",
    "createdAt": "2025-02-18T14:30:00Z"
  }
}

El webhook incluye los encabezados configurados en la transmisión de logs más Content-Type: application/json y User-Agent: Auris-LogStream/1.0. Las entregas se reintentan hasta 3 veces con retroceso exponencial (5s, 30s, 120s) en respuestas que no sean 2xx.

Relacionado

Transmisión de Logs — Transmite registros de auditoría a servicios externos como Datadog y Splunk
Registros y Cumplimiento — Ver y filtrar registros desde la Consola