Skip to main content

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:

FieldDescription
actionWhat happened (e.g., flag.update)
resourceTypeType of resource affected
resourceIdID of the affected resource
resourceNameHuman-readable resource name
userIdWho performed the action
beforeResource state before the change
afterResource state after the change
changesDiff of changed fields
timestampWhen it happened (ISO 8601)
ipAddressClient IP address
userAgentClient user agent string

Actions

Flag Actions

ActionTrigger
flag.createNew flag created
flag.updateFlag configuration changed (targeting, variants, metadata)
flag.deleteFlag removed
flag.toggleFlag enabled/disabled state flipped (also by a trigger or share link: metadata.capability)
flag.rollback / flag.auto_rollbackFlag rolled back by hand or by the circuit breaker
flag.canary_start / flag.canary_advance / flag.canary_abort / flag.canary_completeCanary rollout lifecycle
flag.owner_changeFlag owner (team or person) changed

Service Actions

ActionTrigger
service.createNew service created
service.updateService configuration changed
service.deleteService removed
rollout.deletedA 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

ActionTrigger
member.addUser added to project
member.removeUser removed from project
member.role_changeUser's role updated
member.access_changePer-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

ActionTrigger
invitation.createInvitation sent
invitation.acceptInvitation accepted
invitation.cancelInvitation 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

ActionTrigger
token.createAPI token generated
token.updateToken permissions changed
token.revokeToken revoked
token.rotateToken rotated (the new token keeps the original creator)

Filed on the flag. Entries record the kind of credential that minted the capability, never the trigger token or the link id.

ActionTrigger
trigger.createFlag trigger URL created
trigger.revokeFlag trigger URL revoked
share_link.createShare link (view or toggle) created
share_link.revokeShare 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=50

Filter by Action

GET /api/audit?projectId=proj-1&action=flag.toggle

Every 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-v2

Filter by Date Range

GET /api/audit?projectId=proj-1&startDate=2025-07-01&endDate=2025-07-31

Filter by User

GET /api/audit?projectId=proj-1&userId=user-123

Combined Filters

GET /api/audit?projectId=proj-1&action=flag.update&resourceId=checkout-v2&startDate=2025-07-15&limit=20

Response 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