Audit Logs

⚡ 4 min read

An append-only trail of member actions in your project — custom app events via the SDK, step-up MFA outcomes, and (for AI agents) a narrow guard_gate_decision trail when step-up verification is consumed or session creation fails.

Every row is tied to a member (name, email, role, IP, user agent). The server enriches rows automatically — do not send identity fields from the client.

Which token writes the log?

Different surfaces authenticate differently, but all rows land in the same project audit log.

Surface	Token	Stored where	What gets logged
Your web app (SDK)	SDK access JWT (`aud: transcodes-sdk`)	Browser secure storage after Signin	`trackUserAction()` from your code; step-up MFA on Transcodes Auth when redirectToStepUp runs
AI agent (transcodes-guard)	MAT — Member Access Token (`aud: transcodes-mcp`)	`{{HOME_DIR}}/.transcodes/config.json` via transcodes CLI	`guard_gate_decision` (hook, two outcomes only) and step-up MFA rows written by Transcodes Auth — all attributed to the MAT member
Console operator	Firebase session (human)	Browser	View and export only — not the actor for agent rows

The agent acts as the MAT member. If Alice’s token is in the CLI, risky commands and retire_member appear under Alice in Audit Logs — even when Bob is at the keyboard.

No MAT configured: transcodes-guard still denies risky commands, but step-up cannot start — and nothing is written to Audit Logs (the hook cannot authenticate to the backend without a token).

Recording events (SDK)

From your app, use the SDK while the user is signed in. Login and logout are not logged automatically — after hosted sign-in succeeds, and before token.signOut(), call trackUserAction with member:login / member:signout.


// After sign-in
await transcodes.trackUserAction({
  tag: 'member:login',
  severity: 'medium',
  status: true,
  metadata: { method: 'hosted-redirect' },
});
 
// Before sign-out
await transcodes.trackUserAction({
  tag: 'member:signout',
  severity: 'medium',
  status: true,
});
await transcodes.token.signOut();
 
// Other sensitive actions
await transcodes.trackUserAction({
  tag: 'documents:delete',
  severity: 'high',
  status: true,
  metadata: { documentId: 'doc_123' },
});

Field	Notes
`tag`	Convention: `{resource}:{action}` (e.g. `member:login`)
`severity`	`low` · `medium` · `high`
`status`	`true` = success, `false` = failure

Pass { webhookNotification: true } as the second argument to force an outbound notification (see Webhook).

API reference: Audit API.

After transcodes-guard is installed

Once the host plugin is active and a MAT is saved in the CLI, no manual trackUserAction is needed for MCP step-up MFA. The hook writes a narrow guard_gate_decision trail; Transcodes Auth writes the MFA ceremony rows.

Guard v3 records guard_gate_decision only for step-up MFA outcomes — not for every hook block. A pending step-up (browser opened, MFA not finished) writes no audit row; you may still get a session webhook with the verify URL.

What is logged automatically

Event	Audit tag	Severity	Notes
Human completes MFA on Transcodes Auth	`{resource}:{action}` or `mcp:stepup`	high	`metadata.type: mcp-stepup`, `status: true`, `method: passkey \| totp \| …`
Wrong MFA or verify failure on Transcodes Auth	`{resource}:{action}` or `mcp:stepup`	high	`status: false`, same metadata shape
Same command retries after verified session (verification consumed)	`guard_gate_decision`	low	`metadata.decision: allow`, plus resource, action, rule id, optional `fp` — not the raw command
Backend refused to create a step-up session	`guard_gate_decision`	medium	`metadata.decision: deny-stepup-failure`
Hook blocks command; step-up session created (MFA pending)	—	—	Not logged
RBAC deny (permission 0 — step-up cannot help)	—	—	Not logged
RBAC allow without step-up (permission 1)	—	—	Not logged
No MAT in CLI	—	—	Not logged — hook cannot authenticate
Ungated / safe command	—	—	Not logged

Webhooks: guard_gate_decision rows are low or medium — they do not trigger audit webhooks. When a step-up session is created, Transcodes Cloud may send a separate session webhook (verify URL) even though no gate audit row was written. Completed or failed MFA on Transcodes Auth is high severity and does trigger audit webhooks. Details: Webhook.

Ask your agent to read logs

After install, prompt the agent — it calls the get_security_logs MCP tool (RBAC: system:read on the MAT member’s role):


Show audit logs from the last 24 hours tagged guard_gate_decision.
List recent mcp:stepup events and who approved them.

Install and token setup: AI Agent (MCP).

Viewing logs

Console: Authentication Kit Cluster → Audit Logs — charts and searchable history. Filter by member, tag, severity, or date range.

API: GET /v1/audit/logs (Console session or project API token). Filters: date range, tag, member_id, severity.

MCP: get_security_logs — same data, scoped to the MAT’s project. Useful filters: tag=guard_gate_decision, tag=mcp:stepup, ISO start_date / end_date.

Retention by plan (query window):

Plan	History
Free	Today + yesterday (~2-day query window)
Standard	60 days
Enterprise	Unlimited

Queries outside your plan window return 403.

AI Agent (MCP)Webhook RBAC Audit API