Audit Log

GraphQL `auditLogs`

Reads audit log entries that Atom writes for authorization checks, logins, logouts, lifecycle changes, and credential operations.

Successful high-volume authz.check, auth.login, and gRPC credential-authentication allow events are not written to audit_logs by default. Atom counts them in metrics and emits traces instead. Set ATOM_AUDIT_HOT_PATH_ALLOW_DB_ENABLED=true to persist those allow events too. Deny/error audit events, explicit authz.explain calls, admin mutations, lifecycle events, and credential changes remain durable DB audit.

Arguments

Parameter	Type	Default	Description
`actorEntityId`	UUID	—	Filter by entity that performed the action
`targetKind`	string	—	Filter by target object kind, such as `entity`, `resource`, `tenant`, `credential`, or `role`
`targetId`	UUID	—	Filter by target object ID
`tenantId`	UUID	—	Filter by tenant-scoped audit entries
`event`	string	—	Filter by event type
`outcome`	`allow` \| `deny` \| `error`	—	Filter by outcome
`from`	datetime (ISO 8601)	—	Start of time range (inclusive)
`to`	datetime (ISO 8601)	—	End of time range (exclusive)
`limit`	int	50	Results per page (1-200)
`offset`	int	0	Pagination offset

Response

{
  "items": [
    {
      "id": "log1-...",
      "actorEntityId": "svc-...",
      "targetKind": "resource",
      "targetId": "r1-...",
      "event": "authz.check",
      "outcome": "deny",
      "details": {
        "action": "write",
        "reason": "no matching allow policy"
      },
      "createdAt": "2026-04-24T10:30:00Z"
    },
    {
      "id": "log2-...",
      "actorEntityId": "aaa-...",
      "targetKind": "entity",
      "targetId": "aaa-...",
      "event": "auth.login",
      "outcome": "allow",
      "details": {
        "identifier": "alice"
      },
      "createdAt": "2026-04-24T10:25:00Z"
    }
  ],
  "total": 142
}

Event types

Event	When it's written	Details contain
`authz.check`	Authorization check decision; successful allows require `ATOM_AUDIT_HOT_PATH_ALLOW_DB_ENABLED=true`	`action`, `resource_id`, `reason`
`authz.explain`	Authorization explanation decision	`action`, `resource_id`, `reason`
`auth.login`	Login decision; successful allows require `ATOM_AUDIT_HOT_PATH_ALLOW_DB_ENABLED=true`	`identifier`
`auth.logout`	Session revocation	`{}`
`entity.update` / `entity.enable` / `entity.disable` / `entity.delete` / `entity.restore` / `entity.purge`	Entity lifecycle changes	changed fields or status where relevant
`resource.update` / `resource.delete` / `resource.restore` / `resource.purge`	Resource lifecycle changes	changed fields where relevant
`credential.create`	Password or access-token credential created	`kind`, optionally `credential_id`
`credential.revoke`	Credential revoked	`credential_id`

Use cases

Query	Endpoint
Why was channel-01 denied in the last hour?	`auditLogs(targetKind: "resource", targetId: "...", event: "authz.check", outcome: deny, from: "2026-04-24T09:30:00Z")`
Failed login activity today, plus successful logins when hot-path allow DB audit is enabled	`auditLogs(event: "auth.login", from: "2026-04-24T00:00:00Z")`
All audit events for Alice	`entityAuditLogs(entityId: "...")`
All failed authorization checks	`auditLogs(event: "authz.check", outcome: deny, limit: 100)`

Audit logs are immutable — there are no write or delete operations on this endpoint.

GraphQL auditLogs

Arguments

Response

Event types

Use cases

On this page

GraphQL `auditLogs`