Audit Log

The Pulsabase Audit Log provides a tamper-evident record of all significant actions performed in your project. Audit events are streamed to ClickHouse via NATS and retained independently of your main database.

Architecture

pulsabase-idp / pulsabase-core / pulsabase-edge / pulsabase-storage
    └── NATS Audit stream → pulsabase-audit-writer → ClickHouse (pulsabase_audit)

All services publish audit.* events to a dedicated, isolated NATS cluster (nats-audit). The audit writer consumes and persists them durably.

What’s Logged

Authentication Events (from pulsabase-idp)

Event	Description
`user.signed_in`	Successful password or OAuth login
`user.sign_in_failed`	Failed password / OTP attempt
`user.signed_out`	Explicit sign-out
`user.token_refreshed`	Tokens refreshed via refresh_token
`user.password_reset_requested`	Password reset email triggered
`user.password_reset_confirmed`	Password changed via reset link
`user.password_changed`	Password changed while authenticated
`user.mfa_enrolled`	TOTP MFA enrolled for a user
`user.mfa_disabled`	TOTP MFA disabled for a user
`user.email_verified`	User confirmed their email
`user.created`	New user registered (email or OAuth)
`user.disabled`	User account disabled by admin
`user.deleted`	User account deleted

Access Control Events

Event	Description
`role.created`	New role created
`role.deleted`	Role deleted
`permission.created`	New permission defined
`permission.assigned`	Permission assigned to a role
`role.assigned_to_user`	Role granted to a user
`provider.upsert`	OAuth provider configured
`provider.delete`	OAuth provider removed

Schema & Deployment Events

Event	Description
`schema.deployed`	`db:sync` applied schema changes
`schema.rolled_back`	`db:rollback` executed
`function.deployed`	Edge function created or updated
`function.deleted`	Edge function deleted
`cron.created`	Cron job created
`webhook.created`	Webhook endpoint registered

Storage Events

Event	Description
`storage.upload.completed`	File successfully uploaded
`storage.upload.failed`	File upload rejected (ACL or quota)
`storage.download`	File download presigned URL issued
`storage.delete`	File deleted
`storage.policy.updated`	ACL policy changed for a folder

Edge Function Events

Event	Description
`edge.invoked`	Function invoked (sync or async)
`edge.invoked.success`	Function completed successfully
`edge.invoked.error`	Function failed (step error or timeout)

Viewing Audit Logs

Access audit logs from Dashboard → Audit:

Filters Available

Filter	Options
Date range	Last 1h / 24h / 7d / 30d / custom
Event type	Category or specific event name
User	Filter by actor email or user ID
IP address	Filter by source IP
Status	All / success / failure

Log Entry Structure

Each audit event contains:

Field	Description
`timestamp`	Exact UTC timestamp (microsecond precision)
`event_type`	Event name (e.g., `user.signed_in`)
`actor_id`	User ID who performed the action (or `system`)
`actor_email`	User’s email at time of action
`project_id`	The project affected
`resource_type`	What was acted upon (`user`, `schema`, `file`, etc.)
`resource_id`	ID of the specific resource
`status`	`success` or `failure`
`ip_address`	Client IP address
`user_agent`	Client user-agent string
`metadata`	Structured context (provider name, old/new values, error message)

Compliance & Export

Audit logs can be exported in JSON or CSV format via Dashboard → Audit → Export:

# API export (requires admin token)
curl "https://your-idp.pulsabase.io/management/projects/{project_id}/audit-logs?format=json&from=2026-01-01&to=2026-03-01" \
  -H "Authorization: Bearer <admin_access_token>"

Retention

Tier	Retention
Default	90 days
Enterprise	1 year+ (configurable)

Audit logs are stored in ClickHouse with a time-ordered schema, making large-range queries (for compliance exports) very fast even at high volume.