Audit Logs overview - Circle Docs

The Audit Logs API returns an immutable record of security-relevant actions taken in your Circle entity, such as user sign-ins, approval requests, and policy changes. Use it to review who did what, when, and from where.

Availability

The Audit Logs API is available across all Circle products. Call it with the API key from whichever Circle product you’re integrating with.

Retrieve audit log events

You can retrieve audit log events with two endpoints:

List audit logs returns a paginated, newest-first list, filterable by time range, event type, actor, and outcome.
Get an audit log by ID returns a single audit log event by its id.

Actor types

Every audit log event identifies an actor with actorId and actorType. The actor type tells you what kind of identifier actorId is.

Actor type	What it represents
`USER`	A human who performed the action through the Circle Console, Mint Console, or CPN Console. `actorId` is the user’s identifier.
`API_KEY`	A Circle API key that performed the action programmatically. `actorId` is the API key’s identifier.
`SYSTEM`	Circle-internal automation that performed the action on your entity’s behalf, such as expiring an approval request on its scheduled deadline.

Action events and state-change events

Every audit log event is either an action event or a state-change event. The type field tells you which, and determines which fields carry the event’s details.

Action events record that something happened, with no prior or new resource state to compare.
State-change events record a change to a resource in your entity, such as a policy update.

Both action and state-change events share a common set of fields that identify who did what and when, such as id, type, occurredAt, or actorId. For action events, additional fields specific to that event appear on payload. State-change events populate oldValues (prior state) and newValues (new state); payload might also carry additional context.

Example action event

A user.signed_in event is an action event. It carries the client’s user agent on payload:

{
  "id": "abcdef01-2345-4678-9abc-def012345678",
  "type": "user.signed_in",
  "occurredAt": "2026-07-14T15:58:27.093995Z",
  "actorId": "example-user-id",
  "actorType": "USER",
  "clientIp": "203.0.113.42/32",
  "outcomeResult": "SUCCESS",
  "entityId": "deadbeef-1234-4567-89ab-cdef01234567",
  "requestId": "example-request-id-001",
  "payload": {
    "user_agent": "Mozilla/5.0 ..."
  }
}

Example state-change event

A policy.applied event is a state-change event. It carries oldValues and newValues alongside payload:

{
  "id": "01234567-89ab-4cde-8f01-234567890abc",
  "type": "policy.applied",
  "occurredAt": "2026-07-14T16:02:11.842Z",
  "actorId": "example-user-id",
  "actorType": "USER",
  "outcomeResult": "SUCCESS",
  "entityId": "deadbeef-1234-4567-89ab-cdef01234567",
  "requestId": "example-request-id-002",
  "oldValues": {
    "status": "inactive"
  },
  "newValues": {
    "status": "active"
  },
  "payload": {
    "action": "policy_change",
    "operation": "ACTIVATE",
    "scope": "RESOURCE"
  }
}

Audit log event types

The following event types are recorded in the audit log. The list grows over time as new products and controls add events. Your integration should tolerate unknown type values and unknown keys inside payload. Action events recorded when a user signs in to the Circle Console, Mint Console, or CPN Console. Actor is USER (see the example action event).

Event type	Recorded when
`user.signed_in`	A user signed in to a Circle console.

Each event’s payload might carry the following fields:

Field	Type	Required	Description
`email`	string	No	Email address of the user who signed in, if available.
`user_agent`	string	No	`User-Agent` header of the authenticating client.

Policy Engine events

Circle’s Policy Engine records an immutable event each time an approval request is resolved or a policy changes state. See Policy configuration, permissions, and approvals setup to set up policies and approval rules.

Approval request events

Action events recorded when an approval request is resolved. Actor is USER (see the example action event).

Event type	Recorded when
`proposal.approved`	The request received the required approvals; the action is authorized to proceed.
`proposal.rejected`	An approver rejected the request.
`proposal.expired`	The request reached its expiration window without completing the required approvals and was closed automatically.
`proposal.cancelled`	The initiator withdrew their own pending request before a decision was reached.

Each event’s payload might carry the following fields:

Field	Type	Required	Description
`action`	string	Yes	The governed action the proposal concerns.
`kind`	string	No	Proposal kind: `PROPOSAL`, `POLICY_CHANGE`, or `LIST_CHANGE`.
`policy_id`	string	No	Identifier of the related policy.

Policy change events

State-change events recorded across the lifecycle of a policy change. Actor is USER or SYSTEM. These populate oldValues and newValues (see the example state-change event).

Event type	Recorded when
`policy.change_requested`	A policy create, revision, or delete was submitted and is awaiting approval.
`policy.applied`	An approved policy change took effect.

Each event’s payload might carry the following fields:

Field	Type	Required	Description
`action`	string	Yes	The policy action being performed.
`operation`	string	Yes	Operation applied: `ACTIVATE`, `SUPERSEDE`, or `DELETE`.
`scope`	string	Yes	Scope: `RESOURCE`, `GROUP`, or `WILDCARD`.
`policy_lookup_key`	string	No	Lookup key of the affected policy.
`previous_version_id`	string	No	Identifier of the prior policy version.
`proposal_id`	string	No	Identifier of the driving proposal.

​Availability

​Retrieve audit log events

​Actor types

​Action events and state-change events

​Example action event

​Example state-change event

​Audit log event types

​Sign-in events

​Policy Engine events

​Approval request events

​Policy change events

Availability

Retrieve audit log events

Actor types

Action events and state-change events

Example action event

Example state-change event

Audit log event types

Sign-in events

Policy Engine events

Approval request events

Policy change events