Read the audit trail¶

Your organisation's audit trail records every change to its people, groups, roles, attributes, rules, invitations and settings. This page shows how to read and filter it. What it holds and what it does not is in Roles and access.

org-admin or auditor reads the audit trail. It has no screen in OS yet: you read it through the API. The examples use $OS, $TOKEN and $ORG as in Manage groups.

Read the trail¶

curl -s "$OS/api/v1/organisations/$ORG/audit-events?limit=100" \
    -H "Authorization: Bearer $TOKEN"

OS returns the rows oldest first, in pages of at most 200 (50 by default). Pass next_cursor as cursor for the next page. A row looks like this:

{"id": 4182, "at": "2026-10-17T09:12:00Z", "request_id": "...",
 "actor_membership_id": "mem_...", "actor_organisation_id": "org_...",
 "event": "role.assigned", "kind": "role", "thing_id": "ras_...",
 "changes": {"role": [null, "people-admin"], "reach": [null, "organisation"],
             "member_id": [null, "mem_..."]},
 "allowed_actions": ["see"]}

Filter¶

Add one or more filters to the query:

• event=membership.deactivated: only this event;
• kind=group: only changes to one kind of thing;
• actor=mem_...: only what one person did.

curl -s "$OS/api/v1/organisations/$ORG/audit-events?event=rule.replaced" \
    -H "Authorization: Bearer $TOKEN"

Which events there are¶

An accepted invitation also writes a row for every role, group and value it gave.

What the trail does not hold¶

No passwords, tokens, keys and no e-mail addresses: an invitation is recorded by its id. After a person is erased, their membership ids are still there, but they identify nobody any more.

A change to people or settings is in the trail at once. Changes to memberships and invitations reach it in the background, shortly after. When you read a page again you also see rows recorded later; the trail is for reading, not for following live.

How long the trail is kept¶

Rows are kept for 400 days by default; then OS deletes them. The period is the organisation's audit_retention_days. Only your operator changes it; ask there if you need another period.

At Artific Core too¶

OS also delivers every row to your organisation's audit trail at Artific Core, within a few minutes. There it sits among Core's own events, under Calls and product events, with Artific OS as its origin and os. before the event's name, such as os.role.assigned. So at Core you read one trail of everything that happened in your organisation.

Core shows a changed field as before and after. A field holding a list, such as an attribute's allowed values, is shown as two fields: allowed_values_before and allowed_values. A field Core cannot keep, such as a role's rules or a group's labels, is not there but named under omitted; OS's trail keeps it whole. Rows from before OS started delivering are in OS's trail only.

This works once Artific Core's operator has switched it on for OS. Until then the rows wait, and OS's trail is complete on its own.

When OS refuses¶