Skip to main content
Each change to a policy saves a numbered version. Old versions are never edited. Any version can be viewed, compared, or restored.

What a version captures

A version is a snapshot of what the policy enforces: its name, description, type, scope, priority, active state, and full rule set. Assignments (which agents, wallets, or cards a policy applies to) are tracked separately and are not part of a version. Conto appends a new version whenever you:
  • Create a policy (version 1).
  • Change its metadata (name, description, priority, scope, or active state).
  • Add, edit, replace, or remove any rule.
  • Roll back to an earlier version (the rollback itself is recorded as a new version).
Versions are numbered per policy, starting at 1 and increasing by one.

List the history

Returns versions newest first. Each has version, changeType (CREATED, UPDATED, RULES_CHANGED, or ROLLED_BACK), note, createdBy, createdByType, createdAt, and rulesCount. Page with limit (default 50, up to 100) and offset.

Read one version

Returns the full snapshot for that version, including every rule.

Compare two versions

The diff has fields for metadata that changed, rulesAdded and rulesRemoved for rules, and unchanged, which is true when the two versions match. Rules are compared by content, so a rule that only changed position is not reported, and an edited rule shows up as one removed plus one added.

Roll back

Rollback restores the policy’s definition and rules from the target version and appends a new ROLLED_BACK version. The policy type is fixed for the life of a policy and is never changed by a rollback. Scope is restored with the rest, except on a team policy. Rolling an organization policy back to an assigned version returns 409 with code ROLLBACK_LEAVES_POLICY_UNASSIGNED, because an assigned policy with no assignments applies to no agent. Change its scope to assigned and add assignments first.
Rollback is a change to a live control, so it runs through the same governance approval workflow as any other policy edit when your organization requires it. See Require a second approver for changes. If the target version is organization-scoped but the policy currently has assignments, rollback returns 409 until you remove the assignments, because organization policies apply automatically and cannot be assigned. A team policy stays on its team. An agent’s admin SDK key cannot roll back a policy, because an earlier version can be looser. Rollback returns 400 when a rule in the target version would fail the checks a new rule gets, such as a value the engine cannot read or ALLOW on a blocklist type. A Manager’s rollback always waits for an Owner or Admin.

Audit trail

Version history is for reviewing and restoring policy state. It is separate from the tamper-evident audit log, which independently records every policy change in a per-organization hash chain. See the audit integrity section on the security page.