Track every change to flags, services, members, and tokens with comprehensive audit logs
Last updated November 21, 2026
Audit Logging
Flaggr automatically records an audit trail for every state-changing operation. Every flag toggle, member addition, token creation, and configuration change is logged with full context.
What's Logged
Every audit entry captures:
| Field | Description |
|---|---|
action | What happened (e.g., flag.update) |
resourceType | Type of resource affected |
resourceId | ID of the affected resource |
resourceName | Human-readable resource name |
userId | Who performed the action |
before | Resource state before the change |
after | Resource state after the change |
changes | Diff of changed fields |
timestamp | When it happened (ISO 8601) |
ipAddress | Client IP address |
userAgent | Client user agent string |
Actions
Flag Actions
| Action | Trigger |
|---|---|
flag.create | New flag created |
flag.update | Flag configuration changed (targeting, variants, metadata) |
flag.delete | Flag removed |
flag.toggle | Flag enabled/disabled state flipped (also by a trigger or share link: metadata.capability) |
flag.rollback / flag.auto_rollback | Flag rolled back by hand or by the circuit breaker |
flag.canary_start / flag.canary_advance / flag.canary_abort / flag.canary_complete | Canary rollout lifecycle |
flag.owner_change | Flag owner (team or person) changed |
Service Actions
| Action | Trigger |
|---|---|
service.create | New service created |
service.update | Service configuration changed |
service.delete | Service removed |
rollout.deleted | A non-live rollout plan (draft, completed, failed, rolled back or cancelled) removed with its service (DELETE /api/services/{id} or a tag cleanup, DELETE /api/cleanup) |
rollout.deleted entries carry metadata: rolloutPlanId, flagKey, serviceId, environment, previousStatus, reason (service_deleted or tag_cleanup) and, when the plan's pending or approved rollout_start change requests were retired with it, retiredChangeRequests ([{ changeRequestId, previousStatus }]). A retired request is marked expired, with the reason as a comment. The entries are filed like the other rollout events (resourceType: "project", resourceId the project ID, resourceName the plan's name).
Member Actions
| Action | Trigger |
|---|---|
member.add | User added to project |
member.remove | User removed from project |
member.role_change | User's role updated |
member.access_change | Per-environment/service access overrides changed |
member.remove entries record reason (removed, left, org_removed). When an organization owner takes over a project during an organization removal, a member.add or member.role_change entry carries metadata.reason: "ownership_transfer".
Invitation Actions
| Action | Trigger |
|---|---|
invitation.create | Invitation sent |
invitation.accept | Invitation accepted |
invitation.cancel | Invitation cancelled |
invitation.cancel entries with metadata.reason: "inviter_lost_access" mean Flaggr withdrew an invitation whose inviter was removed or demoted. Organizations log org.invitation_create, org.invitation_accept and org.invitation_cancel (projectId is the organization ID).
Token Actions
| Action | Trigger |
|---|---|
token.create | API token generated |
token.update | Token permissions changed |
token.revoke | Token revoked |
token.rotate | Token rotated (the new token keeps the original creator) |
Trigger & Share Link Actions
Filed on the flag. Entries record the kind of credential that minted the capability, never the trigger token or the link id.
| Action | Trigger |
|---|---|
trigger.create | Flag trigger URL created |
trigger.revoke | Flag trigger URL revoked |
share_link.create | Share link (view or toggle) created |
share_link.revoke | Share link revoked |
Personal access tokens log personal_token.create, personal_token.revoke and personal_token.rotate against the account (projectId is user:<id>), not against a project.
Querying Audit Logs
Basic Query
GET /api/audit?projectId=proj-1&limit=50Filter by Action
GET /api/audit?projectId=proj-1&action=flag.toggleEvery audit action is a valid action filter, and every resource type (flag, service, project, member, invitation, token, experiment, organization, org_member, org_invitation, sso_connection, alert_firing, team) is a valid resourceType.
Filter by Resource
GET /api/audit?projectId=proj-1&resourceType=flag&resourceId=checkout-v2Filter by Date Range
GET /api/audit?projectId=proj-1&startDate=2025-07-01&endDate=2025-07-31Filter by User
GET /api/audit?projectId=proj-1&userId=user-123Combined Filters
GET /api/audit?projectId=proj-1&action=flag.update&resourceId=checkout-v2&startDate=2025-07-15&limit=20Response Format
{
"logs": [
{
"id": "audit-abc123",
"projectId": "proj-1",
"userId": "user-123",
"action": "flag.update",
"resourceType": "flag",
"resourceId": "checkout-v2",
"resourceName": "Checkout V2",
"before": {
"enabled": false,
"targeting": []
},
"after": {
"enabled": true,
"targeting": [
{
"id": "beta-users",
"conditions": [{ "property": "betaUser", "operator": "equals", "value": true }],
"value": true
}
]
},
"changes": [
{ "field": "enabled", "oldValue": false, "newValue": true },
{ "field": "targeting", "oldValue": [], "newValue": "[1 rule]" }
],
"metadata": {},
"timestamp": "2025-07-20T10:30:00Z",
"ipAddress": "203.0.113.1",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
}
],
"total": 150,
"limit": 50,
"offset": 0
}Permissions
Audit logs require project-level read access. Any project member (viewer, member, admin, or owner) can view audit logs for their project.
Callers who can see a project only through a public floor (every signed-in user on the shared demo project and the landing-page showcase) get a reduced view on every audit and history endpoint. They see flag, service, rollout, experiment, impact-forecast and AI entries only. Other people's identity is replaced by "Another member"; the caller's own entries and system entries keep their actor. IP addresses, user agents, before/after state, diffs, summaries and metadata are removed. They can filter by actor only for themselves, and by action only for the actions they can see. Pagination (nextCursor, hasMore) covers only the entries they can see. The same rules apply to the notification feed, to toggle-impact data (recentToggles, latestToggle) and to the release-intelligence graph. Every other record they can read follows the same identity rule. createdBy/updatedBy read "redacted" unless they are the caller's own id or system on: flags (including the toggle response and history snapshots), services, experiments, rollout plans (and each stage's approvedBy), metric sources, environments, AI judges and cohorts. Alert channels and metric sources hide email recipients, addresses and direct @-mentions, and floor callers can't assign flag owners. Project members see the full trail.
Storage
Audit logs are stored in Postgres (flaggr.audit_logs) with an in-memory cache of the most recent 1,000 entries for fast queries. Older entries are read directly from storage.
Use Cases
- Compliance — Track who changed what, when, and from where
- Debugging — Trace a flag misconfiguration back to the change that caused it
- Rollback decisions — View the before/after state to decide whether to rollback
- Team visibility — See what your teammates have been working on
- Incident response — Correlate flag changes with production incidents
Related
- REST API Reference — Audit log query parameters
- Webhooks — Real-time event notifications