Audit Log API

Align records an audit trail of mutations and access-control denials. Organization admins can retrieve it through a filterable API - a named SOC 2 monitoring control.

Append-only is enforced in application code

The application only ever inserts into the audit table; it never updates or deletes. That is currently an application-level property rather than a database constraint, so a role with direct database access could still alter history. If your controls require database-enforced immutability, revoke UPDATE and DELETE on audit_logs from the application role.

Endpoint

GET /admin/audit-logs

• Auth: authenticated request (session cookie or Authorization: Bearer <token>), org_admin role required (403 otherwise).
• Scope: results are restricted to the caller's tenant.

Query parameters

Parameter	Type	Description
action	string	Filter by action. Values are namespace:verb with a colon, e.g. access:denied, decision:deleted, connector:enabled, data:exported. Exact match only.
actor	string	Filter by the actor (user) who performed the action.
resourceType	string	Filter by resource type.
resourceId	uuid	Filter by a specific resource.
from	ISO 8601	Start of the time range.
to	ISO 8601	End of the time range.
limit	int (1-1000)	Page size (default 100).
offset	int	Pagination offset.

Example

curl -s "$ALIGN_API/admin/audit-logs?action=access:denied&from=2026-06-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Each entry includes the actor, action, resource, a details object, and a timestamp.

Coverage and scope

What is recorded today: access-control denials from the permission middleware, connector enable/disable and credential access, decision deletion, user role, permission and activation changes, and the GDPR data-lifecycle events (export, deletion, legal hold, session revocation).

Not currently recorded: plain authentication failures (401s) and the 403 returned by this endpoint's own admin guard. Legal hold applies to decision snapshots, not to audit records - see Data Retention. No retention job purges audit_logs, so the trail is retained for the life of the tenant.