> ## 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, freezing accounts, is recorded in an immutable audit log with SHA-256 hash chains for tamper detection.

## 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                          |
| `ALERT_CREATED` / `ALERT_RESOLVED`          | Alert lifecycle                                |
| `SETTINGS_CHANGED`                          | Organization settings modified                 |
| `PERMISSION_GRANTED` / `PERMISSION_REVOKED` | Role or scope changes                          |
| `LOGIN` / `LOGOUT`                          | User session events                            |
| `AUDIT_LOG_EXPORTED`                        | Audit log data exported                        |

### Resources

Logs track actions on: `agent`, `wallet`, `transaction`, `policy`, `policy_rule`, `organization`, `user`, `member`, `api_key`, `sdk_key`, `alert`, `counterparty`, `relationship`, `settings`, `approval_request`, `approval_workflow`, `payment_request`.

## Log Entry Fields

Each audit log entry contains:

| Field           | Description                                              |
| --------------- | -------------------------------------------------------- |
| `action`        | What happened (CREATE, UPDATE, DELETE, etc.)             |
| `resource`      | What type of resource was affected                       |
| `resourceId`    | ID of the affected resource                              |
| `previousState` | State before the change (JSON)                           |
| `newState`      | State after the change (JSON)                            |
| `actorType`     | Who did it: USER, API, AGENT, or SYSTEM                  |
| `actorId`       | User ID, API key ID, or "system"                         |
| `ipAddress`     | Client IP (from reverse proxy headers)                   |
| `userAgent`     | Client user agent string                                 |
| `metadata`      | Additional context (audit hash, change diff, API key ID) |
| `createdAt`     | When the action occurred                                 |

## Change Detection

When a resource is updated, the audit service automatically diffs the previous and new states and records which fields changed:

```json theme={null}
{
  "changes": [
    { "field": "status", "oldValue": "ACTIVE", "newValue": "SUSPENDED" },
    { "field": "spendLimitDaily", "oldValue": 1000, "newValue": 500 }
  ]
}
```

## Tamper-Evident Hash Chain

Each log entry includes a SHA-256 hash computed over the previous entry's hash, the timestamp, action, resource, and state data. This creates a chain where modifying any entry invalidates all subsequent hashes.

You can verify chain integrity from the signed-in dashboard session:

```bash theme={null}
curl "https://conto.finance/api/audit-logs/verify?startDate=2026-01-01T00:00:00Z&endDate=2026-04-07T00:00:00Z" \
  -H "Cookie: $CONTO_DASHBOARD_COOKIE"
```

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

### Dashboard API

```bash theme={null}
curl "https://conto.finance/api/audit-logs?resource=agent&action=SUSPEND&limit=20" \
  -H "Cookie: $CONTO_DASHBOARD_COOKIE"
```

The dashboard audit-log routes use the signed-in browser session and do not accept SDK keys or
organization API keys. Set `CONTO_DASHBOARD_COOKIE` to the full Cookie header from a signed-in
dashboard request. Agents that only 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 capture the client IP address using platform-set headers in this priority order:

1. `cf-connecting-ip` (Cloudflare)
2. `x-real-ip` (nginx)
3. `x-forwarded-for` first entry (Vercel)

This allows tracing actions back to specific network locations for security investigations.