Audit events

Every read and mutation — through the app or the API — writes an audit event: who did it, what changed, and when. Even retrieving a passport records a read event, so the log lets you reconstruct exactly how your data reached its current state. Reading the log is a privileged operation: only team admins and owners may query it.

The audit event model

Retention per action type is a per-team setting the API can both read and change. Lab actions such as lab_transform and lab_rollback are written here too — see Lab.

List audit events

curl -G https://api.synexcloud.com/v1/audit_events \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -d "created[gte]=1751328000" \
  -d "action[]=create" \
  -d "action[]=modify" \
  -d "order=desc"

{
  "object": "list",
  "data": [
    {
      "object": "audit_event",
      "created": "2026-07-12T09:31:00Z",
      "action": "modify",
      "user": { "id": 42, "name": "Jane Ops" },
      "passport": { "id": "pass_8f2k7d9a1b2c3d4e", "friendly_id": "PACK-001" },
      "context": {
        "property_id": "property_9f2k7d",
        "old_value": "4400",
        "value": "4500"
      }
    },
    {
      "object": "audit_event",
      "created": "2026-07-12T09:29:00Z",
      "action": "read",
      "user": { "id": 42, "name": "Jane Ops" },
      "passport": { "id": "pass_8f2k7d9a1b2c3d4e", "friendly_id": "PACK-001" },
      "context": {}
    },
    {
      "object": "audit_event",
      "created": "2026-07-12T09:20:00Z",
      "action": "lab_transform",
      "user": { "id": 7, "name": "Sam Admin" },
      "passport": null,
      "context": { "run_id": 3187, "matched": 128 }
    }
  ],
  "has_more": true,
  "next_cursor": "ae_01J8Z9QK7M4RXN",
  "url": "/v1/audit_events"
}

Retention settings

How long the log keeps an entry is a per-team setting, and the API can both read and change it. The object is four integers — one per audited action, in days, where 0 means keep forever.

Both operations carry the same gate as reading the log itself: the key's owner must be a team admin or owner, and a key whose owner is neither gets 403 audit_role_required however its abilities are configured. audit:write is additionally not in a key's default ability set — you have to grant it deliberately, which is the intended amount of friction for a setting that governs how long your own evidence survives.

A change is not retroactive

This is the paragraph to read twice: changing retention does nothing whatever to entries already written. Retention is enforced by a TTL attribute stamped on each audit row at write time, so already-written rows keep the window they were written with.

What that means in practice:

• If you shorten retention to satisfy a compliance requirement, the log does not shrink — every entry already in it lives out the window it was born with, on the old policy.
• If you lengthen retention after a gap, the gap stays — nothing refills the period that already expired.

Retention is a decision about the future only. Make it before the data you need is gone, rather than at the point you notice it missing.

Which window to tune

read is by far the highest-volume of the four: every passport read writes an entry, and most integrations read far more than they write. It is consequently the shortest window most teams set, and the first one to look at if the log is larger or noisier than you want.

Retrieve retention settings

curl https://api.synexcloud.com/v1/audit_settings \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "audit_settings",
  "create": 365,
  "modify": 365,
  "delete": 730,
  "read": 30
}

Update retention settings

curl -X PATCH https://api.synexcloud.com/v1/audit_settings \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"read": 30}'

{
  "object": "audit_settings",
  "create": 365,
  "modify": 365,
  "delete": 730,
  "read": 30
}