# Audit Events

Every mutating API call leaves an immutable audit event in the organization's
audit log. Events are retained indefinitely and paginated by cursor.

## Endpoint

### GET /v1/organizations/{org}/audit-events

**Query parameters:**

| Parameter | Description |
|---|---|
| `after` | Cursor — the numeric event ID to start after (for pagination) |
| `limit` | Number of events to return. Must be 1–200 (default: 50) |

**Response `200 OK`:**

```json
{
  "events": [
    {
      "id": 1042,
      "organization_id": "acme",
      "actor": "user|abc123",
      "action": "create_environment",
      "resource_kind": "environment",
      "resource_id": "production",
      "occurred_at": "2026-01-01T12:00:00Z",
      "metadata": {
        "project_id": "store",
        "kind": "production",
        "data_mode": "snapshot"
      }
    }
  ],
  "next_cursor": 1043
}
```

When `next_cursor` is `null`, there are no more events.

## Audited actions

| Action | Description |
|---|---|
| `put_organization` | Organization created or updated |
| `put_member` | Member role added or changed |
| `put_project` | Project created or updated |
| `create_environment` | Environment provisioned |
| `delete_environment` | Environment deleted |
| `suspend_environment` | Environment suspended |
| `resume_environment` | Environment resumed |
| `run_migrations` | Migrations applied |
| `register_branch` | Branch registered |
| `merge_branch` | Branch merged |
| `import` | Supabase import executed |

## CLI

```sh
# Latest 50 events
scribase audit list acme

# Paginate: events after cursor 1000, up to 100
scribase audit list acme 1000 100
```

## Notes

- Audit events are append-only and cannot be modified or deleted.
- The `actor` field contains the OIDC subject of the API caller.
- `metadata` varies by action — it records the key parameters of the call.