Audit Logs

The audit API uses its own scopes, distinct from the ledger scopes: a key needsaudit:write to send events and audit:readto read, verify, and export. Grant them on an API key in Settings. Every example below is a complete request, swap invoance_live_xxx for your key.

The Python and Node SDKs expose the same surface under client.audit. They defaultoccurred_at to now, generate the idempotency key, and ship an offline verifier that needs no network call.

from invoance import InvoanceClient, verify_audit_event

async with InvoanceClient() as client:
    ev = await client.audit.events.ingest(
        organization_id="org_01J8F3KQ2R7VWX9YB4ND6MCZAH",
        action="user.signed_in",
        actor={"type": "user", "id": "user_123", "name": "Ada"},
    )
    stored = await client.audit.events.get(ev["event_id"])
    print(verify_audit_event(stored).valid)   # True — verified offline

import { InvoanceClient, verifyAuditEvent } from "invoance";

const client = new InvoanceClient();
const ev = await client.audit.events.ingest({
  organization_id: "org_01J8F3KQ2R7VWX9YB4ND6MCZAH",
  action: "user.signed_in",
  actor: { type: "user", id: "user_123", name: "Ada" },
});
const stored = await client.audit.events.get(ev.event_id as string);
console.log(verifyAuditEvent(stored).valid);  // true — verified offline

Already on Clerk or Auth0? Skip instrumentation entirely: point your auth provider's webhooks at Invoance and every organization in your app starts accumulating signed audit events (sign-ins, membership changes, role updates) with orgs auto-created as their events arrive. The Integrations overview covers how it works and the shared delivery semantics; the Clerk and Auth0 guides have the setup steps and curated event maps.

The hosted viewer also ships as a React component: @invoance/audit-viewerrenders the same signed event table, filters, export, and in-browser Ed25519 tamper test inside your own product (admin.yourapp.com/audit). Native DOM, no iframe; the stylesheet is prefixed and themed by CSS variables, and verification still runs in your customer's browser, so the proof never depends on trusting the page that renders it.

npm install @invoance/audit-viewer

Your backend mints a short-lived portal session for the signed-in customer. This runs server-side only: the API key must never reach the browser; only the one-time token does.

// A route in YOUR backend (server-side only; never expose the API key)
const session = await client.audit.portalSessions.create({
  organization_id: currentCustomerOrgId,   // your id for this customer
  intent: "audit_logs",
  session_duration_seconds: 3600,
});
return { token: session.token };           // one-time token, safe for the browser

import { AuditLogViewer } from "@invoance/audit-viewer";
import "@invoance/audit-viewer/styles.css";

<AuditLogViewer
  getPortalToken={async () => {
    const r = await fetch("/api/audit-portal-token", { method: "POST" });
    return (await r.json()).token;
  }}
/>

The component exchanges the token for an org-scoped session and re-invokes your callback when it expires, so short sessions cost nothing. Sessions minted with intent: "log_streams" render the stream-destination screen instead. Props, theming, and session behavior are covered in the Embeddable viewer guide.