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

# Audit events

> Read the insert-only trail of credential, session, and account actions in your org.

Sente writes an audit event whenever something sensitive happens to an account — a credential is read or overwritten, a browser session is opened or exported, a connection is revoked, a run is taken over. The trail is **insert-only**: there is no API to edit or delete an event, and events outlive the resources they describe.

Events are org-scoped and never carry secret values — no passwords, no TOTP seeds, no session state. `meta` holds only descriptive fields (see the action table below).

## The audit event object

```json theme={null}
{
  "id": "aud_4c3b2a1908f7e6d5c4b3a2918f7e6d5c",
  "action": "credentials.read",
  "subjectType": "registration",
  "subjectId": "reg_1c2d3e4f5a6b708192a3b4c5d6e7f801",
  "meta": null,
  "createdAt": "2026-07-20T11:42:07.884Z"
}
```

| Field         | Description                                                                                                         |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `action`      | What happened. See the table below.                                                                                 |
| `subjectType` | `registration`, `identity`, or `run` — what the action was performed on. `null` for the rare event with no subject. |
| `subjectId`   | The subject's id. `null` when `subjectType` is.                                                                     |
| `meta`        | Action-specific JSON, or `null`. Never secret values.                                                               |

## Actions

These are the actions the API emits today.

| Action                | Subject      | `meta`                            | What it means                                                                                                                                                         |
| --------------------- | ------------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `registration.create` | registration | `{ credentialOrigin, appOrigin }` | A Sente-created account row was opened for an app. `credentialOrigin` is `generated` or `supplied` — whether Sente made the password or you did.                      |
| `connection.create`   | registration | `{ appOrigin, hasTotp }`          | You connected an account you already own. `hasTotp` says whether a TOTP seed was vaulted with it.                                                                     |
| `connection.revoke`   | registration | —                                 | The delegation was withdrawn; the vault is kept.                                                                                                                      |
| `connection.delete`   | registration | —                                 | The connection was revoked **and** its vaulted secrets purged.                                                                                                        |
| `credentials.read`    | registration | —                                 | The vaulted username/password was returned in plaintext via `GET /v1/registrations/:id/credentials`. Sente-created accounts only — connected accounts are write-only. |
| `credentials.write`   | registration | —                                 | The vault was overwritten via `PUT /v1/registrations/:id/credentials`.                                                                                                |
| `session.open`        | identity     | `{ registrationId }`              | A logged-in browser session was handed out (`POST /v1/registrations/:id/session`).                                                                                    |
| `session.close`       | identity     | —                                 | The live session was released (`DELETE /v1/registrations/:id/session`).                                                                                               |
| `session.export`      | registration | —                                 | A Playwright `storageState` was exported. This is a bearer credential for the account — treat this event as a high-signal one.                                        |
| `run.intervene`       | run          | —                                 | A human paused a live run to take over the browser.                                                                                                                   |
| `run.resume`          | run          | —                                 | A blocked run was handed back to the agent.                                                                                                                           |
| `run.abort`           | run          | —                                 | A run was aborted.                                                                                                                                                    |
| `identity.delete`     | identity     | `{ email }`                       | An identity and everything under it was hard-deleted. The event keeps the address, which no longer exists anywhere else.                                              |

<Note>
  Run *outcomes* (`completed`, `failed`, `blocked`) are not audit events — they live on the run itself and on the [webhooks](/api-reference/webhooks). The audit trail records deliberate acts on credentials, sessions, accounts, and takeover.
</Note>

## List audit events

`GET /v1/audit-events`

| Query param | Type      | Required | Description                                         |
| ----------- | --------- | -------- | --------------------------------------------------- |
| `action`    | string    | no       | Exact match on one action, e.g. `credentials.read`. |
| `since`     | ISO date  | no       | Only events at or after this timestamp.             |
| `limit`     | int 1–200 | no       | Default 50. Newest first.                           |

```bash theme={null}
curl "https://api.sente.run/v1/audit-events?action=session.export&limit=100" \
  -H "Authorization: Bearer sk_sente_..."
```

Response `200`: an array of audit event objects, newest first.

```json theme={null}
[
  {
    "id": "aud_4c3b2a1908f7e6d5c4b3a2918f7e6d5c",
    "action": "session.export",
    "subjectType": "registration",
    "subjectId": "reg_1c2d3e4f5a6b708192a3b4c5d6e7f801",
    "meta": null,
    "createdAt": "2026-07-20T11:42:07.884Z"
  },
  {
    "id": "aud_9182a3b4c5d6e7f80192a3b4c5d6e7f8",
    "action": "connection.create",
    "subjectType": "registration",
    "subjectId": "reg_1c2d3e4f5a6b708192a3b4c5d6e7f801",
    "meta": { "appOrigin": "https://app.example.com", "hasTotp": true },
    "createdAt": "2026-07-20T11:05:19.302Z"
  }
]
```

An unknown `action` is not an error — it just matches nothing and returns `[]`. There is no pagination cursor: page by narrowing `since` and raising `limit`.

Another org's events are never returned, and there is no endpoint to fetch a single event by id.