Access ledger

Every permission change in Halcyon is written to an append-only ledger. Each entry records the actor, the resource, the previous value and the reason supplied at the time of the change.

Immutability

Entries are never edited. A correction is a new entry that supersedes the old one, so the history of a resource can always be replayed exactly as it happened.

This is why the ledger is the only source support quotes from during an incident review.

Retention

Retention follows the workspace plan: ninety days on Team, one year on Scale and seven years on Enterprise. Expired entries are removed by a nightly sweep that itself writes a summary entry.

Export

Workspace owners can export the ledger as newline-delimited JSON. Exports are generated asynchronously and expire after 24 hours.

Large workspaces are chunked at one million entries per file so the download survives a flaky connection.

Reading the ledger

The read API is cursor paginated and ordered by sequence, not timestamp, because two entries can share a millisecond.

Filters

Filters compose with AND. Filtering by actor and resource together is the common case for support, and both are indexed.

Rate limits

Reads are limited to sixty requests per minute per token. A 429 carries a Retry-After header, and clients should honour it rather than backing off on their own schedule.