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

# Audit Log

> Cursor-paginated access to your org's HIPAA audit log with tamper-evident integrity hashing.

Cursor-paginated access to your org's HIPAA audit log. Requires the `control:read` scope.

Every significant event on the platform — record operations, schema changes, webhook deliveries, API key issuance, budget updates, AI requests — is written to this log. Every event participates in a tamper-evident integrity hash chain per ADR-JVSATA.

## List audit entries

```
GET https://api.usehasp.com/v1/audit
Authorization: Bearer hasp_api_live_...
```

### Query parameters

| Parameter     | Type    | Description                                                                                  |
| ------------- | ------- | -------------------------------------------------------------------------------------------- |
| `action`      | string  | Filter to entries with this exact action string (e.g. `api_key.created`).                    |
| `entity_type` | string  | Filter by entity type (e.g. `app`, `organization`).                                          |
| `entity_id`   | string  | Filter by entity ULID. Combine with `entity_type` to get all events for a specific resource. |
| `cursor`      | string  | Cursor from a previous response `meta.next_cursor`. Omit for the first page.                 |
| `limit`       | integer | Page size. Min `1`, max `200`. Default `50`.                                                 |

### Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "01JQAUDIT0000000000000000",
      "action": "webhook_endpoint.created",
      "entity_type": "app",
      "entity_id": "01JQAPP00000000000000000",
      "user_id": null,
      "ip_address": "203.0.113.42",
      "metadata": {
        "url": "https://example.com/hooks/hasp",
        "events": ["record.created"],
        "source": "api"
      },
      "integrity_hash": "a3f9c2d8...",
      "created_at": "2026-05-02T10:00:00+00:00"
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6Ij...",
    "has_more": true
  }
}
```

### Fields

| Field            | Description                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `id`             | ULID of the audit entry. Globally unique.                                                                   |
| `action`         | What happened. See [Action reference](#action-reference) below.                                             |
| `entity_type`    | The type of resource the action was performed on (e.g. `app`, `organization`). `null` for org-level events. |
| `entity_id`      | ULID of the specific resource. `null` if not resource-scoped.                                               |
| `user_id`        | ULID of the user who performed the action. `null` for API-key-initiated actions or system events.           |
| `ip_address`     | IPv4 or IPv6 address of the request origin.                                                                 |
| `metadata`       | Action-specific context. Shape varies by action.                                                            |
| `integrity_hash` | SHA-256 hash for tamper detection. Always present — every event participates in a per-org integrity chain.  |
| `created_at`     | ISO 8601 timestamp.                                                                                         |

Results are ordered by `created_at DESC` (newest first). The cursor encodes the position of the last-seen row.

## Action reference

Common action strings you will encounter:

| Action                     | Triggered by                                                |
| -------------------------- | ----------------------------------------------------------- |
| `api_key.created`          | New API key issued                                          |
| `api_key.revoked`          | API key revoked                                             |
| `budget.updated`           | Spend cap, alert thresholds, or Opus toggle changed via API |
| `webhook_endpoint.created` | Outbound webhook endpoint registered                        |
| `webhook_endpoint.updated` | Endpoint URL, events, or active state changed               |
| `webhook_endpoint.deleted` | Endpoint deleted                                            |
| `webhook_secret.rotated`   | Signing secret rotated                                      |
| `record.created`           | Data record created                                         |
| `record.updated`           | Data record updated                                         |
| `record.deleted`           | Data record deleted                                         |
| `schema.updated`           | App entity schema modified                                  |
| `ai_request.completed`     | AI API request completed (HIPAA audit event)                |

## Integrity hash chain

Every audit entry's `integrity_hash` is a SHA-256 hash of the entry's content chained to the previous entry's hash for that organization. This creates a tamper-evident log: modifying any past entry breaks all subsequent hashes, making tampering detectable. The chain is universal per ADR-JVSATA — every org participates, including Free Evaluation and the synthetic HASP internal org used for cross-org system events. The chain is verified automatically as part of HASP's internal audit tooling.

## Error codes

| Code                | HTTP | Description                                      |
| ------------------- | ---- | ------------------------------------------------ |
| `INVALID_API_KEY`   | 401  | Invalid or revoked token                         |
| `MISSING_SCOPE`     | 403  | Key lacks `control:read` scope                   |
| `VALIDATION_FAILED` | 422  | `limit` out of range or invalid filter parameter |