> ## 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 Auditoria

> Rastreie toda a atividade da API, eventos de segurança e auditoria de conformidade.

Truthlocks mantém logs de auditoria abrangentes para monitoramento de segurança, relatórios de conformidade e solução de problemas operacionais.

## O que é Registrado

Toda operação de API gera um evento de auditoria. Isso inclui operações bem-sucedidas, tentativas falhas e eventos relevantes para a segurança.

> [card] Operações de API
>
> * Cunhagem de atestação \* Revogação de atestação \* Emissor
>   criação/modificação \* Registro de chave

> [card] Eventos de Segurança
>
> * Falhas de autenticação \* Permissão negada \* Limite de taxa excedido \*
>   Atividade suspeita

> [card] Ações de Governança
>
> * Aprovação/rejeição do emissor \* Suspensão do emissor \* Atribuições de função \* Chave de API
>   gerenciamento

> [card] Atividade do Usuário
>
> * Login/logout de usuário \* Mudanças de senha \* Convites de usuário \* Mudanças de função

## Estrutura do Evento de Auditoria

Cada evento de auditoria contém contexto detalhado sobre o que aconteceu, quem o fez e quando:

```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 | Descrição |
| - | - | - |
| `actor_type` | string | Quem realizou a ação: `USER`, `API_KEY`, ou `SERVICE` |
| `actor_id` | string | UUID do usuário, chave de API ou serviço que acionou o evento |
| `action` | string | A operação realizada (por exemplo, `attestation.mint`) |
| `resource_type` | string | Tipo de recurso afetado (por exemplo, `attestation`, `issuer`, `user`) |
| `resource_id` | string | UUID do recurso afetado |
| `service` | string | O serviço de backend que tratou a solicitação (por exemplo, `trust-registry`, `audit-service`) |
| `outcome` | string | `SUCCESS` ou `FAILURE` |
| `metadata` | objeto | Contexto específico da ação, como ID do emissor, tipo de reivindicação ou detalhes do erro |
| `integrity_hash` | string | Hash SHA-256 para verificação de evidência de adulteração |

## Consultando Logs de Auditoria

### 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 | Descrição |
| - | - | - |
| `action` | string | Filtrar por tipo de ação (por exemplo, `attestation.mint`) |
| `actor_id` | string | Filtrar por usuário ou ID da chave de API |
| `resource_type` | string | Filtrar por recurso (atestado, emissor, usuário) |
| `from` | datetime | Eventos após este horário (ISO 8601) |
| `to` | datetime | Eventos antes deste horário (ISO 8601) |
| `limit` | inteiro | Máximo de eventos a retornar (padrão 50, máximo 1000) |
| `cursor` | string | Cursor de paginação para a próxima página |

## Trilha de auditoria de decisão de política

Cada avaliação de [política de emissão](https://docs.truthlocks.com/pt/guides/issuance-policies.md) é automaticamente registrada como um evento de auditoria. Cada registro captura o `decision_id`, versão da política, regras correspondentes, tempo de avaliação e um hash SHA-256 da entrada para evidência de adulteração. Consulte as decisões da 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 [trilha de auditoria de decisão](https://docs.truthlocks.com/pt/guides/issuance-policies.md#decision-audit-trail) para a lista completa de campos registrados.

## Casos de uso comuns

### Investigação de segurança

Encontrar todas as tentativas de autenticação falhadas para um ator específico:

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

### Relatório de Conformidade

Exportar todas as operações de atestado para um período de tempo:

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

### Revisão da Atividade do Usuário

Veja tudo o que um usuário específico fez:

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

## Retenção de logs

| Nível | Retenção padrão | Formato de exportação |
| - | - | - |
| Grátis | 7 dias | Somente JSON |
| Iniciante | 30 dias | JSON, CSV |
| Profissional | 90 dias | JSON, CSV, integração SIEM |
| Enterprise | 1 ano (personalizado disponível) | Todos os formatos + streaming em tempo real |

> [!NOTE]
>
> Para requisitos de conformidade que excedam o seu nível
> período de retenção, configure a integração SIEM para transmitir logs para o seu próprio
> infraestrutura.

### Políticas de retenção personalizadas

Você pode configurar por quanto tempo os logs de auditoria são retidos e se os logs expirados são arquivados ou excluídos permanentemente. Defina políticas de retenção globalmente ou por ambiente.

| Campo | Tipo | Descrição |
| :- | :- | :- |
| `retention_days` | integer | Dias para manter os logs de auditoria (30–3.650) |
| `hard_delete` | boolean | Se `true`, exclua permanentemente os logs expirados. Se `false`, arquive-os. |
| `export_allowed` | boolean | Se as exportações de auditoria são permitidas para este escopo |
| `environment_id` | string | Opcional. Aplique esta política apenas a um ambiente específico. |

A política padrão retém logs por 365 dias, arquiva (exclui suavemente) logs expirados e permite exportações.

**Obtenha sua política de retenção atual:**

```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
}
```

**Atualizar a política de retenção:**

```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
  }'
```

Quando existe uma política específica do ambiente, ela tem precedência sobre a política global. Se nenhuma política específica do ambiente for definida, a política global se aplica.

> [!WARNING]
>
> Alterar `hard_delete` para `true` remove permanentemente os logs assim que eles ultrapassam a janela de retenção. Esta ação não pode ser desfeita. Certifique-se de ter exportado todos os logs de que precisa antes de habilitar a exclusão permanente.

A atualização das configurações de retenção requer a permissão `tenant.audit.retention.manage`. A visualização das configurações requer `tenant.audit.retention.read`.

## Integração SIEM

Clientes empresariais podem transmitir logs de auditoria em tempo real para sistemas externos de gerenciamento de informações e eventos de segurança (SIEM).

### Provedores suportados

| Provedor | Transporte | Formato |
| :- | :- | :- |
| **Splunk** | HTTP Event Collector (HEC) | JSON |
| **Datadog** | API de Gerenciamento de Logs | JSON |
| **AWS CloudWatch** | Assinatura de logs | JSON |
| **Elastic/ELK** | Ingestão Elasticsearch | JSON |
| **Webhook personalizado** | HTTP POST | JSON |

Configure um destino de streaming em **Configurações > Auditoria > SIEM** no console, ou gerencie destinos programaticamente através da [API de configuração SIEM](https://docs.truthlocks.com/pt/api-reference/audit/siem/create.md). Para instruções de configuração passo a passo do provedor, consulte o [guia de integração SIEM](https://docs.truthlocks.com/pt/guides/siem-integration.md).

### Criar um 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"
}
```

Substitua `provider` por um de `splunk`, `datadog`, `cloudwatch`, `elastic`, ou `webhook`. Cada provedor requer um `endpoint` de destino e uma credencial de autenticação (`token` para Splunk, Datadog e Elastic; `access_key_id` e `secret_access_key` para CloudWatch; `secret` para webhooks personalizados).

### Listar destinos SIEM

Recupere todos os destinos de streaming configurados para seu locatário.

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

### Atualizar um destino SIEM

Altere o endpoint, as credenciais ou o estado habilitado de um 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
  }'
```

### Excluir um destino SIEM

Remover um destino de streaming. Os eventos em trânsito são descarregados antes de o destino ser eliminado.

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

### Entrega e buffer

Uma vez ativado, cada evento de auditoria é transmitido para o seu destino em tempo real, juntamente com o registo padrão na plataforma. Se o destino estiver inacessível, os eventos são armazenados em buffer e retentados com backoff exponencial por até 24 horas. Pode monitorizar a saúde da entrega no campo `status` devolvido pelo endpoint de lista — os valores possíveis são `active`, `degraded` (a tentar novamente) e `failed`.

> [!WARNING]
>
> **Recurso Empresarial:** O streaming de logs em tempo real requer o nível Enterprise.
> Entre em contato com o departamento de vendas para obter assistência na configuração.

## Próximos passos

> [card] [Integração SIEM](https://docs.truthlocks.com/guides/siem-integration.md)
>
> Transmita eventos de auditoria para Splunk, Datadog, CloudWatch, Elastic ou um webhook personalizado.

> [card] [Exportações de conformidade](https://docs.truthlocks.com/guides/compliance-exports.md)
>
> Exporte dados de auditoria nos formatos SOC 2, GDPR e HIPAA.

> [card] [Reforço contra abusos](https://docs.truthlocks.com/security/abuse-hardening.md)
>
> Detecte e previna abusos usando dados de auditoria.

> [card] [Limites de taxa](https://docs.truthlocks.com/ops/limits.md)
>
> Entenda o comportamento de limitação de taxa nos logs de auditoria.


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