> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Logs

> Tamper-evident audit trail for all actions in your organization

# Audit Logs

Every action in Conto, creating agents, executing payments, changing policies, and freezing
accounts, is recorded in a database-enforced append-only audit log with SHA-256 hash chains for
tamper detection in normal operation. Privileged database operations and backup restoration remain
outside that guarantee until records are also anchored in externally controlled WORM storage.

## What Gets Logged

### Actions

| Action                                      | Description                                    |
| ------------------------------------------- | ---------------------------------------------- |
| `CREATE`                                    | Resource created (agent, wallet, policy, etc.) |
| `UPDATE`                                    | Resource modified                              |
| `DELETE`                                    | Resource removed                               |
| `APPROVE` / `REJECT`                        | Approval decision made                         |
| `SUSPEND` / `ACTIVATE`                      | Agent frozen or unfrozen                       |
| `FUND` / `WITHDRAW` / `TRANSFER`            | Wallet balance changes                         |
| `PAYMENT_EXECUTED`                          | Payment submitted onchain                      |
| `PAYMENT_CONFIRMED`                         | Payment confirmed onchain                      |
| `PAYMENT_DENIED`                            | Payment blocked by policy                      |
| `PAYMENT_FAILED`                            | Payment transaction failed                     |
| `EXTERNAL_PAYMENT_APPROVAL`                 | External wallet payment approved               |
| `EXTERNAL_PAYMENT_CONFIRMED`                | External wallet payment confirmed              |
| `POLICY_VIOLATION`                          | Policy rule triggered                          |
| `ASSIGN_POLICY` / `REMOVE_POLICY`           | Agent policy assignment changed                |
| `LINK_WALLET` / `UNLINK_WALLET`             | Agent wallet connection changed                |
| `TRANSACTION_RETRY`                         | Payment retry requested                        |
| `TRUST_SCORE_UPDATE`                        | Counterparty trust assessment refreshed        |
| `ALERT_CREATED` / `ALERT_RESOLVED`          | Alert lifecycle                                |
| `SETTINGS_CHANGED`                          | Organization settings modified                 |
| `PERMISSION_GRANTED` / `PERMISSION_REVOKED` | Role or scope changes                          |
| `LOGIN` / `LOGOUT`                          | User session events                            |
| `INVITE_MEMBER` / `UPDATE_ROLE`             | Team access changed                            |
| `PLAN_CHANGED` / `INVOICE_PAID`             | Billing lifecycle                              |
| `AUDIT_LOG_EXPORTED`                        | Audit log data exported                        |

### Resources

Logs track actions on agents, wallets, transactions, policies, organization members, API and SDK
keys, alerts, counterparties, approval workflows, payment and budget requests, billing, and supported
x402 or MPP payment records.

## Log Entry Fields

Customer audit responses and exports provide these fields for understanding and reconciling an
event:

| Field               | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `id`                | Stable audit entry reference                                 |
| `action`            | Customer-visible action                                      |
| `resource`          | Customer-visible resource type                               |
| `actorType`         | Who performed it: USER, API, AGENT, or SYSTEM                |
| `createdAt`         | When the event occurred                                      |
| `resourceReference` | Supported resource ID, dashboard label, and link             |
| `changes`           | Safe before-and-after values for supported customer fields   |
| `transaction`       | Related payment reference and status, when the event has one |

`resourceReference.id` is present when the affected record has a supported customer reference, so
you can reconcile an audit entry with API records or a support request. Authentication sessions and
generic settings records intentionally return a null reference ID.

```json theme={null}
{
  "id": "log_01JZ...",
  "action": "AGENT_FROZEN",
  "resource": "agent",
  "actorType": "USER",
  "createdAt": "2026-07-15T18:00:00.000Z",
  "resourceReference": {
    "id": "agent_123",
    "label": "Procurement Agent",
    "href": "/agents/agent_123"
  },
  "changes": [
    {
      "field": "status",
      "label": "Status",
      "before": "Active",
      "after": "Suspended"
    }
  ],
  "transaction": null
}
```

## Change Detection

When a resource is updated, `changes` includes only documented customer fields such as status,
name, role, limits, and alert resolution. Arbitrary metadata, network request details,
authentication data, and unsupported state fields are not returned in audit responses or exports.

## Tamper-Evident Hash Chain

Conto maintains a SHA-256 integrity chain for audit entries, so modifying an earlier entry causes a
later verification check to fail.

Owners and admins can verify chain integrity for a selected date range from **Audit Logs** in the
signed-in dashboard.

Response:

```json theme={null}
{
  "verified": true,
  "totalLogs": 1247,
  "verifiedLogs": 1247,
  "brokenAt": null,
  "error": null
}
```

If tampering is detected, the response includes `brokenAt` with the ID of the first compromised entry.

## Viewing Logs

### Dashboard

Go to **Audit Logs** in the sidebar. Filter by:

* Action type
* Resource type
* Actor (user or API key)
* Date range

Agents that need their own audit trail can use the SDK route:

```bash theme={null}
curl "https://conto.finance/api/sdk/audit-logs?resource=payment_request&limit=20" \
  -H "Authorization: Bearer $CONTO_API_KEY"
```

## IP Attribution

Audit logs record the client IP address supplied by Conto's trusted network boundary when one is
available. This helps security investigations without requiring clients to send an IP field.