Before you start
Audit events are for explainability. They should help an operator answer who changed what, when it changed, which Workspace and Project were affected, and which session or request caused it.
Event families
| Family | Examples |
|---|---|
| Authentication | Login, logout, MFA changes, provider links |
| Sessions | Refresh, revoke, scoped access entry |
| Membership | Invite, accept, public join, register, role change |
| Applications | OAuth/OIDC client create, rotate, remove |
| Webhooks | Endpoint create, toggle, remove, test, retry |
| Growth | Campaign send, notification delivery, loyalty activity |
| Security | Policy change, key rotation, suspicious state |
Required fields
- actor ID
- action
- resource type and ID
- Workspace ID
- Project ID when applicable
- environment when applicable
- request or trace ID
- before/after summary when safe
Retention and exports
Retention depends on plan capabilities. Export behavior should preserve enough scope metadata for security review without leaking secrets or bearer tokens.
Security and operational notes
- Never log secrets, raw bearer tokens, or provider private keys.
- Keep sandbox audit logs separate from production audit logs.
- Treat missing audit scope as a product bug, not just a logging gap.
Related docs
- Roles and Permissions:
/docs/concepts/roles-permissions - Webhook Deliveries:
/docs/reference/webhook-deliveries - Plan Limits:
/docs/pricing/limits