Audit Logs
⚡ 4 min readAn append-only trail of member actions in your project — sign-in, step-up, admin changes, custom app events, and transcodes-guard gate decisions.
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; login and step-up ceremonies on Transcodes Auth |
| AI agent (transcodes-guard) | MAT — Member Access Token (aud: transcodes-mcp) | {{HOME_DIR}}/.transcodes/config.json via transcodes CLI | Hook guard_gate_decision rows and step-up MFA rows on 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:
await transcodes.trackUserAction({
tag: 'documents:delete',
severity: 'high',
status: true,
metadata: { documentId: 'doc_123' },
});| Field | Notes |
|---|---|
tag | Convention: {resource}:{action} (e.g. user: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 gated agent actions. The hook and bundled MCP server write to the same backend log as your app.
What is logged automatically
| Event | Audit tag | Severity | Notes |
|---|---|---|---|
| Risky command blocked, step-up session created | guard_gate_decision | medium | metadata.decision: deny-stepup-pending, plus resource, action, rule id, command fingerprint (fp) — not the raw command string |
| 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 with verified session | guard_gate_decision | low | metadata.decision: allow |
| RBAC deny (no step-up path) | guard_gate_decision | medium | metadata.decision: deny-rbac-denied |
| Step-up session could not be created | guard_gate_decision | medium | metadata.decision: deny-stepup-failure |
No MAT in CLI (deny-no-token) | — | — | Not logged — backend audit call is skipped |
| Safe command — hook passes silently | — | — | Not logged (pass) |
Webhooks: the guard_gate_decision row is medium — it does not trigger an audit webhook by itself. When a step-up session is created, Transcodes Cloud sends a separate Slack/Discord alert with the verify URL. Completed step-up rows are high severity and do 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 | ~2 days |
| Standard | 60 days |
| Enterprise | Unlimited |
Queries outside your plan window return 403.