Every request that passes through gateway-proxy, evaluate-action, mcp-gate, or a webhook handler produces an audit_logs row. Rows are append-only — Sentrail never modifies or deletes them outside of scheduled purges (configurable per plan).
What gets logged
| Column | Type | Description |
|---|
id | uuid | Unique log entry ID |
workspace_id | uuid | Workspace that owns this log |
correlation_id | uuid | Links the audit log to its approval request and deferred action |
agent_id | uuid | FK to agent_identities (nullable) |
agent_name | text | String identifier from X-Agent-Id header |
tool | text | github, linear, mcp, system, etc. |
action | text | Classified action string, e.g. pull_request.create |
decision | text | allow, block, require_approval, or error |
risk_level | enum | low, medium, high, critical |
matched_policy_id | uuid | FK to the policy that made the decision (nullable) |
resource_type | text | issue, pull_request, file, etc. |
resource_id | text | e.g. owner/repo#42 |
requested_by | text | Agent ID or email of the requester |
payload_preview | jsonb | Truncated payload for display (not the full body) |
source | text | gateway, webhook, manual, mcp, proxy |
created_at | timestamptz | When the action was evaluated |
Correlation IDs
The correlation_id is a UUID generated at evaluation time and threaded through the entire request lifecycle:
- Created in
evaluate-action-core.ts when the audit log is written
- Returned to the agent in
X-Sentrail-CorrelationId response header
- Stored in
approval_requests.correlation_id
- Used in the
/gateway-proxy/status/:correlationId poll endpoint
- Written to subsequent audit log entries (e.g. approval decision)
You can look up any approval request, deferred action, or audit entry by correlation ID.
Decision values
| Value | Meaning |
|---|
allow | Policy matched and action was forwarded, or default allow |
block | Policy matched and action was rejected |
require_approval | Policy matched and action was deferred for human review |
error | An unexpected error occurred during evaluation |
Source values
| Value | Origin |
|---|
gateway | Came through gateway-proxy |
mcp | Came through mcp-gate |
webhook | Came through webhook-github or webhook-linear |
manual | Created by approval-decision or kill-switch |
proxy | Direct proxy call |
Retention and purging
Audit logs are purged on a schedule based on your plan. The purge-audit-logs cron function runs on the schedule_audit_log_purges schedule. Purge policies are configurable — contact support to adjust retention.
Audit logs are protected by Row Level Security. Members can view logs for their own workspace only. The service role (used by edge functions) can write logs; no user-level role can delete or update them.
Querying audit logs
You can query audit logs through the Supabase client from authenticated frontend code:
const { data } = await supabase
.from("audit_logs")
.select("*")
.eq("workspace_id", workspaceId)
.order("created_at", { ascending: false })
.limit(50);
.eq("correlation_id", "550e8400-e29b-41d4-a716-446655440000")