Exporte o log de auditoria da sua equipe para NDJSON, CSV ou JSON para conformidade, arquivamento e análise posterior.
O que está no log de auditoria
Toda ação que altera o estado da conta — convites, mudanças de papel, rotações de chaves, configurações de site, mudanças de cobrança e mais — é registrada com:
- id — id único da entrada do log
- action — o que aconteceu (ex.:
team.invite_member,website.update_settings) - resource_type + resource_id — sobre o que a ação foi executada
- actor_id — qual membro da equipe executou a ação
- metadata — contexto adicional (origem, IP em hash, etc.)
- created_at — timestamp em UTC
Os endereços IP dentro de metadata são armazenados como hashes unidirecionais com um salt rotacionado diariamente, assim você mantém o valor forense sem expor IPs em texto puro.
Você também pode examinar o mesmo registro de auditoria no painel sob Configurações → Segurança → Audit log.
Disponibilidade por plano
A Exportação de Auditoria está disponível a partir do plano Pro. (Os planos gratuitos não incluem a criação de chaves API, portanto o endpoint não é acessível em Free.)
Autenticação
O endpoint faz parte da External API e é chamado com uma chave API:
Authorization: Bearer YOUR_API_KEY
Gere uma chave API no painel: Configurações → Segurança → API Keys → Nova chave. Uma chave de acesso completo funciona contra cada endpoint.
Se sua conta faz parte de várias equipes, direcione uma equipe específica usando o header X-Zenovay-Team-Id em cada requisição.
Exportar o log de auditoria
curl -L "https://api.zenovay.com/v1/cli/mutate/audit/export?format=ndjson" \
-H "Authorization: Bearer YOUR_API_KEY" \
-o zenovay-audit.ndjson
Formatos suportados
format | Content-Type | Ideal para |
|---|---|---|
ndjson (padrão) | application/x-ndjson | Streaming para pipelines de análise de logs (JSON delimitado por linha) |
csv | text/csv | Abrir no Excel, Google Sheets ou ferramentas de BI |
json | application/json | Array JSON único para processamento programático |
A resposta é enviada com Content-Disposition: attachment; filename="zenovay-audit.<format>" para que a maioria dos clientes HTTP a salve em disco.
A exportação cobre o histórico de auditoria disponível da sua equipe (os audit logs são retidos por 24 meses). Uma única exportação retorna até 10.000 das entradas mais recentes. Para arquivos maiores, execute exportações regulares em um cronograma e adicione-as ao cold storage. Para consultas mais leves e interativas, use /v1/cli/mutate/audit/logs (veja abaixo).
Buscar entradas recentes (paginado)
Para consultas interativas, use /v1/cli/mutate/audit/logs:
curl "https://api.zenovay.com/v1/cli/mutate/audit/logs?since=7d&limit=100" \
-H "Authorization: Bearer YOUR_API_KEY"
Parâmetros de consulta
| Parâmetro | Padrão | Observações |
|---|---|---|
since | 7d | Janela de tempo: 1h, 7d, 4w, 12m |
action | – | Filtrar pela string de ação exata |
actor | – | Filtrar pelo id do usuário |
limit | 50 | Máximo de 200 por requisição |
A resposta inclui pagination.next_cursor quando houver mais entradas além do limit solicitado. Para alcançar entradas mais antigas, aumente limit (até 200) ou reduza a janela since. Para um arquivo completo, use o endpoint de exportação acima, que retorna até 10.000 das entradas mais recentes em uma única chamada.
Melhores práticas
- Agende exportações regulares. Um cron job semanal que armazena o NDJSON em cold storage (S3 Glacier, R2, etc.) é uma forma de baixo custo de manter um rastro imutável.
- Rotacione sua chave API periodicamente e após qualquer offboarding de membro da equipe.
- Trate as exportações como sensíveis. As entradas não são segredos, mas descrevem atividade operacional — mantenha-as fora de buckets públicos e drives compartilhados.
- Combine com webhooks para reagir a ações específicas em tempo real e use a exportação como reconciliação completa periódica.
Erros que você pode ver
| Status | Significado |
|---|---|
401 unauthorized | Chave API ausente ou inválida, ou a chave não está vinculada a uma equipe |
402 upgrade_required | Seu plano não inclui a Exportação de Auditoria — faça upgrade para Pro ou superior |
400 invalid_format | format deve ser um de ndjson, csv, json |
Toda resposta também inclui o header x-request-id. Mantenha-o nos seus tickets de suporte para que possamos rastrear a chamada de ponta a ponta.