> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Registros de Auditoría

> Rastree toda la actividad de la API, eventos de seguridad y auditoría de cumplimiento.

Truthlocks mantiene registros de auditoría completos para monitoreo de seguridad, informes de cumplimiento y resolución de problemas operativos.

## Qué se registra

Cada operación de API genera un evento de auditoría. Esto incluye operaciones exitosas, intentos fallidos y eventos relevantes para la seguridad.

> [card] Operaciones de API
>
> * Acuñación de atestaciones \* Revocación de atestaciones \* Emisor
>   creación/modificación \* Registro de clave

> [card] Eventos de seguridad
>
> * Fallos de autenticación \* Permiso denegado \* Límite de velocidad excedido \*
>   Actividad sospechosa

> [card] Acciones de gobernanza
>
> * Aprobación/rechazo del emisor \* Suspensión del emisor \* Asignaciones de roles \* Clave de API
>   gestión

> [card] Actividad del usuario
>
> * Inicio/cierre de sesión de usuario \* Cambios de contraseña \* Invitaciones de usuario \* Cambios de rol

## Estructura del evento de auditoría

Cada evento de auditoría contiene contexto detallado sobre lo que sucedió, quién lo hizo y cuándo:

```json theme={null}
{
  "id": "evt_abc123",
  "timestamp": "2026-01-13T12:34:56.789Z",
  "tenant_id": "tenant-uuid",
  "actor_type": "USER",
  "actor_id": "user-uuid",
  "action": "attestation.mint",
  "resource_type": "attestation",
  "resource_id": "attestation-uuid",
  "service": "trust-registry",
  "outcome": "SUCCESS",
  "metadata": {
    "issuer_id": "issuer-uuid",
    "subject": "user:12345",
    "claim": "email_verified"
  },
  "integrity_hash": "sha256:abc123..."
}
```

| Campo | Tipo | Descripción |
| - | - | - |
| `actor_type` | string | Quién realizó la acción: `USER`, `API_KEY`, o `SERVICE` |
| `actor_id` | string | UUID del usuario, clave API o servicio que desencadenó el evento |
| `action` | string | La operación realizada (por ejemplo, `attestation.mint`) |
| `resource_type` | string | Tipo de recurso afectado (por ejemplo, `attestation`, `issuer`, `user`) |
| `resource_id` | string | UUID del recurso afectado |
| `service` | string | El servicio de backend que manejó la solicitud (por ejemplo, `trust-registry`, `audit-service`) |
| `outcome` | string | `SUCCESS` o `FAILURE` |
| `metadata` | object | Contexto específico de la acción, como el ID del emisor, el tipo de reclamación o los detalles del error |
| `integrity_hash` | string | Hash SHA-256 para verificación de evidencia de manipulación |

## Consulta de registros de auditoría

### Consulta básica

```bash theme={null}
curl -X GET "https://api.truthlocks.com/v1/audit/events?limit=100" \
  -H "X-API-Key: tl_live_your_api_key"
```

### Consulta filtrada

```bash theme={null}
curl -X GET "https://api.truthlocks.com/v1/audit/events" \
  -H "X-API-Key: tl_live_your_api_key" \
  -G \
  --data-urlencode "action=attestation.mint" \
  --data-urlencode "actor_id=user-uuid" \
  --data-urlencode "from=2026-01-01T00:00:00Z" \
  --data-urlencode "to=2026-01-31T23:59:59Z" \
  --data-urlencode "limit=50"
```

### Parámetros de filtro

| Parámetro | Tipo | Descripción |
| - | - | - |
| `action` | string | Filtrar por tipo de acción (por ejemplo, `attestation.mint`) |
| `actor_id` | string | Filtrar por usuario o ID de clave API |
| `resource_type` | string | Filtrar por recurso (atestación, emisor, usuario) |
| `from` | datetime | Eventos después de esta hora (ISO 8601) |
| `to` | datetime | Eventos antes de esta hora (ISO 8601) |
| `limit` | integer | Eventos máximos a devolver (por defecto 50, máximo 1000) |
| `cursor` | string | Cursor de paginación para la página siguiente |

## Registro de auditoría de decisiones de políticas

Cada evaluación de [política de emisión](https://docs.truthlocks.com/es/guides/issuance-policies.md) se registra automáticamente como un evento de auditoría. Cada registro captura el `decision_id`, la versión de la política, las reglas coincidentes, el tiempo de evaluación y un hash SHA-256 de la entrada para evidencia de manipulación. Consulte las decisiones de la política filtrando por `resource_type=policy_decision`:

```bash theme={null}
curl "https://api.truthlocks.com/v1/audit/events?resource_type=policy_decision&resource_id=dec_7f3a1b" \
  -H "X-API-Key: tl_live_..."
```

Consulte [registro de auditoría de decisiones](https://docs.truthlocks.com/es/guides/issuance-policies.md#decision-audit-trail) para obtener la lista completa de campos registrados.

## Casos de uso comunes

### Investigación de seguridad

Encontrar todos los intentos de autenticación fallidos para un actor específico:

```http theme={null}
GET /v1/audit/events
  ?action=auth.failure
  &actor_id=user-uuid
  &from=2026-01-12T00:00:00Z
```

### Informe de cumplimiento

Exportar todas las operaciones de atestación para un período de tiempo:

```http theme={null}
GET /v1/audit/events
  ?resource_type=attestation
  &from=2026-01-01T00:00:00Z
  &to=2026-01-31T23:59:59Z
  &limit=1000
```

### Revisión de actividad del usuario

Vea todo lo que hizo un usuario específico:

```http theme={null}
GET /v1/audit/events
  ?actor_id=employee-uuid
  &limit=100
```

## Retención de registros

| Nivel | Retención predeterminada | Formato de exportación |
| - | - | - |
| Gratuito | 7 días | Solo JSON |
| Starter | 30 días | JSON, CSV |
| Profesional | 90 días | JSON, CSV, integración SIEM |
| Enterprise | 1 año (personalizado disponible) | Todos los formatos + transmisión en tiempo real |

> [!NOTE]
>
> Para requisitos de cumplimiento que excedan los de su nivel
> período de retención, configure la integración de SIEM para transmitir los registros a su propio
> infraestructura.

### Políticas de retención personalizadas

Puede configurar cuánto tiempo se retienen los registros de auditoría y si los registros caducados se archivan o se eliminan permanentemente. Establezca políticas de retención globalmente o por entorno.

| Campo | Tipo | Descripción |
| :- | :- | :- |
| `retention_days` | integer | Días para mantener los registros de auditoría (30–3,650) |
| `hard_delete` | boolean | Si `true`, eliminar permanentemente los registros caducados. Si `false`, archivarlos. |
| `export_allowed` | boolean | Si se permiten las exportaciones de auditoría para este alcance |
| `environment_id` | string | Opcional. Aplique esta política solo a un entorno específico. |

La política predeterminada retiene los registros durante 365 días, archiva (elimina de forma lógica) los registros caducados y permite las exportaciones.

**Obtenga su política de retención actual:**

```bash theme={null}
curl https://api.truthlocks.com/v1/audit/retention \
  -H "X-API-Key: tl_live_..."
```

```json theme={null}
{
  "retention_days": 365,
  "hard_delete": false,
  "export_allowed": true,
  "environment_id": null
}
```

**Actualizar la política de retención:**

```bash theme={null}
curl -X PUT https://api.truthlocks.com/v1/audit/retention \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "retention_days": 730,
    "hard_delete": false,
    "export_allowed": true
  }'
```

Cuando existe una política específica del entorno, esta tiene prioridad sobre la política global. Si no se establece ninguna política específica del entorno, se aplica la política global.

> [!WARNING]
>
> Cambiar `hard_delete` a `true` elimina permanentemente los registros una vez que pasan la ventana de retención. Esta acción no se puede deshacer. Asegúrese de haber exportado los registros que necesite antes de habilitar la eliminación permanente.

La actualización de la configuración de retención requiere el permiso `tenant.audit.retention.manage`. La visualización de la configuración requiere `tenant.audit.retention.read`.

## Integración SIEM

Los clientes empresariales pueden transmitir registros de auditoría en tiempo real a sistemas externos de información de seguridad y gestión de eventos (SIEM).

### Proveedores admitidos

| Proveedor | Transporte | Formato |
| :- | :- | :- |
| **Splunk** | HTTP Event Collector (HEC) | JSON |
| **Datadog** | API de gestión de logs | JSON |
| **AWS CloudWatch** | Suscripción de registros | JSON |
| **Elastic/ELK** | Ingesta de Elasticsearch | JSON |
| **Webhook personalizado** | HTTP POST | JSON |

Configure un destino de transmisión desde **Configuración > Auditoría > SIEM** en la consola, o gestione destinos programáticamente a través de la [API de configuración de SIEM](https://docs.truthlocks.com/es/api-reference/audit/siem/create.md). Para obtener instrucciones de configuración paso a paso del proveedor, consulte la [guía de integración de SIEM](https://docs.truthlocks.com/es/guides/siem-integration.md).

### Crear un destino SIEM

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/audit/siem \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "splunk",
    "endpoint": "https://hec.splunk.example.com:8088/services/collector",
    "token": "your-hec-token",
    "enabled": true
  }'
```

```json theme={null}
{
  "id": "siem_abc123",
  "provider": "splunk",
  "endpoint": "https://hec.splunk.example.com:8088/services/collector",
  "enabled": true,
  "created_at": "2026-06-30T12:00:00Z",
  "status": "active"
}
```

Reemplace `provider` con uno de `splunk`, `datadog`, `cloudwatch`, `elastic` o `webhook`. Cada proveedor requiere un `endpoint` de destino y una credencial de autenticación (`token` para Splunk, Datadog y Elastic; `access_key_id` y `secret_access_key` para CloudWatch; `secret` para webhooks personalizados).

### Listar destinos SIEM

Recuperar todos los destinos de transmisión configurados para su inquilino.

```bash theme={null}
curl https://api.truthlocks.com/v1/audit/siem \
  -H "X-API-Key: tl_live_..."
```

### Actualizar un destino SIEM

Cambie el endpoint, las credenciales o el estado habilitado de un destino existente.

```bash theme={null}
curl -X PUT https://api.truthlocks.com/v1/audit/siem/siem_abc123 \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://hec-new.splunk.example.com:8088/services/collector",
    "token": "your-new-hec-token",
    "enabled": true
  }'
```

### Eliminar un destino SIEM

Eliminar un destino de transmisión. Los eventos en curso se vacían antes de que se elimine el destino.

```bash theme={null}
curl -X DELETE https://api.truthlocks.com/v1/audit/siem/siem_abc123 \
  -H "X-API-Key: tl_live_..."
```

### Entrega y almacenamiento en búfer

Una vez habilitado, cada evento de auditoría se transmite a su destino en tiempo real junto con el registro estándar en la plataforma. Si el destino no es accesible, los eventos se almacenan en búfer y se reintentan con retroceso exponencial durante un máximo de 24 horas. Puede monitorear el estado de la entrega en el campo `status` devuelto por el punto final de la lista; los valores posibles son `active`, `degraded` (reintentando) y `failed`.

> [!WARNING]
>
> **Característica empresarial:** La transmisión de registros en tiempo real requiere el nivel Enterprise.
> Póngase en contacto con ventas para obtener ayuda con la configuración.

## Próximos pasos

> [card] [Integración SIEM](https://docs.truthlocks.com/guides/siem-integration.md)
>
> Transmita eventos de auditoría a Splunk, Datadog, CloudWatch, Elastic o un webhook personalizado.

> [card] [Exportaciones de cumplimiento](https://docs.truthlocks.com/guides/compliance-exports.md)
>
> Exporte datos de auditoría en formatos SOC 2, GDPR y HIPAA.

> [card] [Refuerzo contra el abuso](https://docs.truthlocks.com/security/abuse-hardening.md)
>
> Detecte y prevenga el abuso utilizando datos de auditoría.

> [card] [Límites de tarifa](https://docs.truthlocks.com/ops/limits.md)
>
> Comprenda el comportamiento de limitación de velocidad en los registros de auditoría.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.