Audit trail

Sente holds passwords, TOTP seeds, and logged-in browser sessions on your behalf. The audit trail is how you answer the question that follows from that: who touched them, and when. Every sensitive act — a credential read in plaintext, a session handed to a caller, a portable session exported, a connection revoked, a run taken over by a person — writes an event you can query. The trail is insert-only. There is no endpoint to edit or delete an event, events outlive the resources they describe, and they are scoped to your organization. meta carries descriptive fields only — never a password, never a TOTP seed, never session state.

This is the pull-based counterpart to webhooks. Run outcomes (completed, failed, blocked) are not audit events — they live on the run and on the run.* webhooks. The audit trail records deliberate acts on credentials, sessions, accounts, and takeover.

Query it

GET /v1/audit-events. There is no SDK or CLI wrapper for this endpoint yet — it is a plain authenticated GET.

# Everything sensitive in the last 24 hours
curl -G https://api.sente.run/v1/audit-events \
  -H "Authorization: Bearer $SENTE_API_TOKEN" \
  --data-urlencode "since=$(date -u -v-1d +%Y-%m-%dT%H:%M:%SZ)" \
  --data-urlencode "limit=200"

# Just the exports — a storageState is a bearer credential for a logged-in account
curl -G https://api.sente.run/v1/audit-events \
  -H "Authorization: Bearer $SENTE_API_TOKEN" \
  --data-urlencode "action=session.export"

type AuditEvent = {
  id: string;
  action: string;
  subjectType: "registration" | "identity" | "run" | null;
  subjectId: string | null;
  meta: Record<string, unknown> | null;
  createdAt: string;
};

const since = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
const res = await fetch(
  `https://api.sente.run/v1/audit-events?since=${encodeURIComponent(since)}&limit=200`,
  { headers: { authorization: `Bearer ${process.env.SENTE_API_TOKEN}` } },
);
if (!res.ok) throw new Error(`audit-events → ${res.status}`);
const events = (await res.json()) as AuditEvent[];

const sensitive = new Set(["credentials.read", "session.export", "connection.delete"]);
for (const e of events.filter((e) => sensitive.has(e.action))) {
  console.log(e.createdAt, e.action, e.subjectType, e.subjectId);
}

import json
import os
import urllib.parse
import urllib.request
from datetime import datetime, timedelta, timezone

since = (datetime.now(timezone.utc) - timedelta(days=1)).isoformat()
query = urllib.parse.urlencode({"since": since, "limit": 200})
req = urllib.request.Request(
    f"https://api.sente.run/v1/audit-events?{query}",
    headers={"authorization": "Bearer " + os.environ["SENTE_API_TOKEN"]},
)
with urllib.request.urlopen(req) as resp:
    events = json.load(resp)

SENSITIVE = {"credentials.read", "session.export", "connection.delete"}
for e in events:
    if e["action"] in SENSITIVE:
        print(e["createdAt"], e["action"], e["subjectType"], e["subjectId"])

Parameters

Param	Type	Description
`action`	string	Exact match on one action value, e.g. `credentials.read`. An unknown value is not an error — it returns `[]`.
`since`	ISO timestamp	Only events at or after this instant.
`limit`	int 1–200	Default 50. Newest first.

Response 200 — an array, newest first:

[
  {
    "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"
  }
]

There is no pagination cursor: page by moving since backwards and raising limit. There is no endpoint to fetch a single event by id, and another org’s events are never returned.

Every action Sente records

This is the complete list of action values the API emits today.

Action	Subject	`meta`	What it means
`registration.create`	registration	`{ credentialOrigin, appOrigin }`	An account row was opened for an app so Sente could sign up. `credentialOrigin` is `generated` (Sente made the password) or `supplied` (you did).
`connection.create`	registration	`{ appOrigin, hasTotp }`	You delegated an account you already own. Its credentials were vaulted; `hasTotp` says whether an authenticator seed came with them. Also written when you re-connect to rotate credentials.
`connection.revoke`	registration	—	Delegated access was withdrawn. The agent can no longer log in; the vault is kept so re-connecting re-enables it.
`connection.delete`	registration	—	The connection was revoked and its vaulted password and TOTP seed were purged. Sente holds nothing for that account afterwards.
`credentials.read`	registration	—	A username and password were returned in plaintext via `GET /v1/registrations/:id/credentials`. Sente-created accounts only — connected accounts are write-only and return `403 CREDENTIALS_WRITE_ONLY`.
`credentials.write`	registration	—	The vault was overwritten via `PUT /v1/registrations/:id/credentials`. This changes what Sente stores, not the password at the app.
`session.open`	identity	`{ registrationId }`	A live browser already signed in to the account was handed to a caller (`POST /v1/registrations/:id/session`).
`session.close`	identity	—	That live session was stopped and released.
`session.export`	registration	—	Cookies and local storage left Sente as a portable Playwright `storageState`. Treat this as the highest-signal event in the trail: the export is a bearer credential for a logged-in account.
`run.intervene`	run	—	A person paused a live run to take manual control of the browser.
`run.resume`	run	—	A blocked run was handed back to the agent.
`run.abort`	run	—	A person stopped a run.
`identity.delete`	identity	`{ email }`	An identity and everything under it — accounts, runs, messages, scoped webhooks — was hard-deleted. The event keeps the address, which no longer exists anywhere else.

meta never contains secret values, and neither does any other field. A credentials.read event tells you a read happened and against which account — it does not contain the credentials. Nor does it identify an individual actor: API keys are org-scoped, so an event records the organization, the action, and the subject — not which person or key performed it.

In the dashboard

app.sente.run → Activity → the Security tab renders the same trail in plain English — “Credentials read”, “Logged-in session exported” — with the sensitive actions highlighted. It is the fastest way to answer “did anything touch our accounts this week” without writing a query.

Practical uses

Alert on credential and session exposure

Poll action=credentials.read, action=session.export, and action=connection.delete on a schedule with since set to your last poll, and forward anything new to your own alerting. Those three are the events where account access left Sente’s control.

Reconstruct what happened to one account

Pull a window with since, then filter client-side on subjectId equal to the account’s reg_… id. Because the trail is insert-only and events outlive their resources, this still works after the connection was deleted.

Prove a delegation was withdrawn

connection.revoke and connection.delete are the durable record that access was withdrawn — useful when the account owner asks for evidence. Pair with the connection’s revokedAt field, which reflects current state rather than history.

Errors

Status	Body	Meaning
`400`	zod issues array	A malformed `since` (not a date) or a `limit` outside 1–200.
`401`	`{"error": "missing api key"}`	No `Authorization: Bearer` or `x-api-key` header.
`401`	`{"error": "invalid api key"}`	The key is wrong or revoked. Mint a new one at app.sente.run.

Next steps

Security model

Where credentials live, how they are encrypted, and who can read them.

Sessions

What session.open and session.export actually hand out.

Webhooks

Push events for mail and run state, as opposed to this pull-based trail.

Audit events API reference

The endpoint contract in reference form.

Get started

Accounts

Runs

Email

Events & audit

Trust

Query it

Parameters

Every action Sente records

In the dashboard

Practical uses

Errors

Next steps

Security model

Sessions

Webhooks

Audit events API reference

​Query it

​Parameters

​Every action Sente records

​In the dashboard

​Practical uses

​Errors

​Next steps

Security model

Sessions

Webhooks

Audit events API reference

Query it

Parameters

Every action Sente records

In the dashboard

Practical uses

Errors

Next steps