Audit Log
Data Entity
Description
Tamper-evident, chronological record of all significant system events, administrative actions, and security-relevant operations across organizations. Supports compliance, forensic investigation, and Global Admin support-access traceability.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
organization_id |
uuid |
Organization whose audit trail this entry belongs to | required |
actor_user_id |
uuid |
User who performed the action; nullable for system-initiated events | - |
actor_role |
enum |
Role of the actor at the time of the action | - |
action |
string |
Machine-readable action identifier, e.g. user.invite, role.assign, session.revoke, support_access.grant | required |
resource_type |
string |
Type of the resource affected, e.g. user, activity, assignment, expense, organization | required |
resource_id |
string |
ID of the specific resource affected; string to accommodate UUIDs and composite keys | - |
outcome |
enum |
Whether the action succeeded or failed | required |
ip_address |
string |
IP address of the request origin | - |
user_agent |
string |
User agent string of the client that performed the action | - |
session_id |
uuid |
Session during which the action was performed; nullable for system actions | - |
before_state |
json |
Snapshot of the resource state before the action (for update/delete); null for create actions | - |
after_state |
json |
Snapshot of the resource state after the action (for create/update); null for delete actions | - |
metadata |
json |
Additional context specific to the action type, e.g. support_access expiry date, bulk action count, export file name | - |
is_support_access_event |
boolean |
True when the action was performed by a Global Admin under a time-bounded support access grant | required |
created_at |
datetime |
Timestamp when the audit event was recorded; set by the server, never by clients | required |
Database Indexes
idx_audit_logs_org_created
Columns: organization_id, created_at
idx_audit_logs_actor
Columns: actor_user_id, created_at
idx_audit_logs_resource
Columns: resource_type, resource_id
idx_audit_logs_action
Columns: action
idx_audit_logs_support_access
Columns: organization_id, is_support_access_event, created_at
Validation Rules
action_format
error
Validation failed
actor_or_system_required
error
Validation failed
organization_exists
error
Validation failed
ip_format
warning
Validation failed
state_snapshots_size_limit
warning
Validation failed
Business Rules
immutable_records
Audit log entries are write-once. No UPDATE or DELETE is permitted after creation. Deletion is only possible via automated retention archival, never via application code or admin UI.
server_side_timestamp
created_at is set by the server at write time using NOW(). Clients may never supply or override this value.
support_access_mandatory_logging
Every action performed by a Global Admin under an org's time-bounded support access grant must set is_support_access_event = true and record the grant expiry in metadata. This is required by the platform's tenant isolation contract.
organization_scoping
Every audit log entry must belong to exactly one organization. System-level events not associated with a specific org are recorded under the Global Admin's administrative organization.
sensitive_field_redaction
before_state and after_state snapshots must redact sensitive fields (passwords, tokens, personal health data) before storage. Redacted fields are replaced with a placeholder string.
outcome_required_on_security_actions
For security-relevant actions (login, session.revoke, role.assign, support_access.*) the outcome field must be explicitly set to success, failure, or denied — never defaulted.