Audit Logging Guide

Overview

Audit logging provides an immutable record of all permission changes in your organization, enabling compliance tracking, debugging, and accountability. Logs are append-only, never modified, and automatically cleaned up based on retention policy.

How It Works

Log Lifecycle

Event Occurs — A role, team, or membership change happens
Log Created — The change is recorded with actor, IP, timestamp, and details
Stored Permanently — Log becomes immutable (read-only forever)
Queryable — Admins can search by actor, resource, action, or date
Cleaned Up — Logs older than retention period are deleted by cleanup job

Audit Actions (MVP)

Action	Triggered By	Details
`member_role_assigned`	Assign custom role to member	Before: [], After: [role_id]
`member_role_removed`	Remove custom role from member	Before: [role_id], After: []
`member_custom_roles_updated`	Update multiple roles at once	Before: [old_ids], After: [new_ids]
`custom_role_created`	Create a new custom role	Role name, permissions
`custom_role_updated`	Modify custom role permissions	Before: [perms], After: [perms]
`custom_role_deleted`	Delete a custom role	Role name, reason
`team_created`	Create new team	Team name, description
`team_updated`	Modify team metadata	Before: , After:
`team_deleted`	Delete team	Team name
`team_role_assigned`	Assign role to team	Role ID, Team ID
`team_role_removed`	Remove role from team	Role ID, Team ID
`member_added_to_team`	Add member to team	Member ID, Team ID
`member_removed_from_team`	Remove member from team	Member ID, Team ID

Querying Audit Logs

Basic Query

Get all audit logs for your organization:

curl "https://api.example.com/api/v1/organizations/org_xyz/audit" \
  -H "Authorization: Bearer <token>"

Filter by Actor

Find all changes made by a specific user:

curl "https://api.example.com/api/v1/organizations/org_xyz/audit?actor_id=user_abc123" \
  -H "Authorization: Bearer <token>"

This is useful for auditing a specific admin’s activities or seeing if someone made unauthorized changes.

Filter by Resource

Track all changes to a specific role:

curl "https://api.example.com/api/v1/organizations/org_xyz/audit?resource_type=role&resource_id=role_abc123" \
  -H "Authorization: Bearer <token>"

Supported resource types:

role — Custom role changes
team — Team CRUD operations
member — Member changes (added, removed, role assignments)

Filter by Date Range

Get logs from the last 30 days:

curl "https://api.example.com/api/v1/organizations/org_xyz/audit?start_date=2026-03-25&end_date=2026-04-25" \
  -H "Authorization: Bearer <token>"

Combined Filters

Find all role-related changes by an admin in the last week:

curl "https://api.example.com/api/v1/organizations/org_xyz/audit?actor_id=user_xyz&resource_type=role&start_date=2026-04-18&pageSize=50" \
  -H "Authorization: Bearer <token>"

Log Format

Example Audit Log Entry

{
  "id": "audit_abc123",
  "orgId": "org_xyz789",
  "actorId": "user_admin_456",
  "action": "member_role_assigned",
  "resourceType": "member",
  "resourceId": "member_xyz789",
  "changes": {
    "before": {
      "customRoleIds": ["role_viewer"]
    },
    "after": {
      "customRoleIds": ["role_viewer", "role_editor"]
    }
  },
  "ipAddress": "192.168.1.100",
  "sessionContext": {
    "sessionId": "sess_abc123",
    "userAgent": "Mozilla/5.0..."
  },
  "approvalStatus": null,
  "approvalMetadata": null,
  "orgRetentionDays": 90,
  "createdAt": "2026-04-24T10:30:00Z"
}

Field Definitions

Field	Type	Description
`id`	UUID	Immutable log ID (can be referenced externally)
`orgId`	UUID	Organization ID
`actorId`	UUID	User who made the change
`action`	String	What happened (member_role_assigned, etc.)
`resourceType`	String	Type of resource changed (role, team, member)
`resourceId`	UUID	ID of resource that changed
`changes`	Object	Before/after state comparison
`ipAddress`	String	IP address of requester (for security audit)
`sessionContext`	Object	Session details for compliance
`approvalStatus`	String	Approval workflow status (future)
`approvalMetadata`	Object	Approval details (future)
`orgRetentionDays`	Integer	Retention policy in effect at log creation
`createdAt`	Timestamp	When the change occurred

Retention Policy

Default Retention

Organizations retain audit logs for a default period (e.g., 90 days). After this period, logs are automatically deleted. The response from the audit API includes the retention period:

{
  "logs": [...],
  "retentionDays": 90
}

Cleanup Process

A scheduled job (cron, Lambda, etc.) calls the cleanup endpoint periodically:

curl -X POST "https://api.example.com/api/v1/organizations/org_xyz/audit/cleanup" \
  -H "Authorization: Bearer <service_token>" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": false}'

Response:

{
  "deleted": 150,
  "retainedFrom": "2026-01-25T00:00:00Z"
}

Dry Run

Test cleanup without deleting:

curl -X POST "https://api.example.com/api/v1/organizations/org_xyz/audit/cleanup" \
  -H "Authorization: Bearer <service_token>" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'

Returns how many logs would be deleted without actually deleting them.

Common Use Cases

Compliance Audit

“Show me all role changes made in Q1 2026”:

curl "https://api.example.com/api/v1/organizations/org_xyz/audit?start_date=2026-01-01&end_date=2026-03-31&resource_type=role" \
  -H "Authorization: Bearer <token>"

Then export to CSV or PDF for compliance teams.

Security Investigation

“Did someone add themselves as an admin without authorization?”:

curl "https://api.example.com/api/v1/organizations/org_xyz/audit?resource_type=member&resource_id=member_suspicious&pageSize=100" \
  -H "Authorization: Bearer <token>"

Review the log history to see all role changes for that member.

Debugging Permission Issues

“Why does Alice not have content:publish permission?”:

# 1. Check current permissions by querying member details or testing can()
# 2. Get role assignment history
curl "https://api.example.com/api/v1/organizations/org_xyz/audit?resource_id=member_alice" \
  -H "Authorization: Bearer <token>"
# 3. Review when roles were added/removed
# 4. Check which teams she's in and their role assignments
curl "https://api.example.com/api/v1/organizations/org_xyz/audit?resource_type=team" \
  -H "Authorization: Bearer <token>"

Admin Activity Review

“What did the new admin do in their first week?”:

curl "https://api.example.com/api/v1/organizations/org_xyz/audit?actor_id=user_new_admin&start_date=2026-04-15&end_date=2026-04-22" \
  -H "Authorization: Bearer <token>"

Best Practices

Regular Audits

Schedule weekly or monthly reviews of audit logs to catch suspicious activity early.

Retention Strategy

Short retention (30 days): For compliance-sensitive data, delete quickly
Standard retention (90 days): Default for most organizations
Long retention (1 year): For highly regulated industries

Immutability Guarantee

Audit logs are guaranteed immutable. They cannot be:

Modified or edited
Deleted except by retention policy
Hidden from queries

This makes them trustworthy for compliance purposes.

IP Address Logging

Logs capture the requester’s IP address for security investigations:

{
  "ipAddress": "192.168.1.100",
  ...
}

Use this to detect unauthorized access patterns or geographic anomalies.

API Pagination

Audit logs support pagination to handle large result sets efficiently:

# Get 20 logs per page (default)
curl "https://api.example.com/api/v1/organizations/org_xyz/audit?page=1" \
  -H "Authorization: Bearer <token>"

# Get 100 logs per page (max)
curl "https://api.example.com/api/v1/organizations/org_xyz/audit?page=1&pageSize=100" \
  -H "Authorization: Bearer <token>"

Response includes:

{
  "logs": [...],
  "total": 1250,
  "page": 1,
  "pageSize": 20
}

Use total to calculate how many pages exist: Math.ceil(total / pageSize).

Error Handling

Insufficient Permissions

{
  "error": "Insufficient permissions to access audit logs"
}

Only members of the organization can view audit logs.

Invalid Filter

{
  "error": "Invalid date range: start_date must be before end_date"
}

Ensure dates are in ISO 8601 format and logically ordered.

Organization Not Found

{
  "error": "Organization not found"
}

Verify the organization ID is correct.

​Audit Logging Guide

​Overview

​How It Works

​Log Lifecycle

​Audit Actions (MVP)

​Querying Audit Logs

​Basic Query

​Filter by Actor

​Filter by Resource

​Filter by Date Range

​Combined Filters

​Log Format

​Example Audit Log Entry

​Field Definitions

​Retention Policy

​Default Retention

​Cleanup Process

​Dry Run

​Common Use Cases

​Compliance Audit

​Security Investigation

​Debugging Permission Issues

​Admin Activity Review

​Best Practices

​Regular Audits

​Retention Strategy

​Immutability Guarantee

​IP Address Logging

​API Pagination

​Error Handling

​Insufficient Permissions

​Invalid Filter

​Organization Not Found

​Related Guides