Audit API

⚡ 5 min read

The trackUserAction() method records actions for audit logs (method name is fixed; tag identifies the event). Use it for sensitive operations, compliance, and activity trails.

Login / logout are not automatic. After hosted sign-in succeeds, and before token.signOut(), call trackUserAction with member:login / member:signout.

trackUserAction()

Records a user action for audit logging. Supports severity levels, success/failure status, and optional metadata


transcodes.trackUserAction(
  event: {
    tag: string;
    severity?: 'low' | 'medium' | 'high';
    status?: boolean;
    error?: string;
    metadata?: Record<string, unknown>;
    page?: string;
  },
  options?: {
    requireAuth?: boolean;
    webhookNotification?: boolean;
    memberId?: string;
    projectId?: string;
  }
): Promise<void>

Event Parameters

Parameter	Type	Required	Description
`tag`	`string`	Yes	Tag identifying the action (e.g., ‘user:login’, ‘document:create’)
`severity`	`'low' \| 'medium' \| 'high'`	No	Severity level. Default: `'low'`
`status`	`boolean`	No	Success/failure. Default: `true`
`error`	`string`	No	Error message when `status: false`
`metadata`	`Record<string, unknown>`	No	Additional metadata (e.g., `{ method: 'passkey' }`)
`page`	`string`	No	Page URL for the audit entry. Default: `window.location.href`

Options

Parameter	Type	Required	Description
`requireAuth`	`boolean`	No	If `true`, calls `redirectToSignIn()` when no member is found. Default: `true`. Set `false` to no-op silently when unauthenticated (no anonymous log)
`webhookNotification`	`boolean`	No	Send Slack webhook regardless of severity. Default: `false`
`memberId`	`string`	No	Skip session lookup and POST as this member (advanced — e.g. step-up context)
`projectId`	`string`	No	Project ID paired with `memberId` (defaults to SDK project)

Examples


// After successful hosted sign-in
await transcodes.trackUserAction({
  tag: 'member:login',
  severity: 'medium',
  status: true,
  metadata: { method: 'hosted-redirect' },
});
 
// Before sign-out (session still valid)
await transcodes.trackUserAction({
  tag: 'member:signout',
  severity: 'medium',
  status: true,
  metadata: { method: 'manual' },
});
await transcodes.token.signOut();

Other actions


await transcodes.trackUserAction({
  tag: 'document:create',
  metadata: { documentId: 'doc_123' },
});

With severity and status


await transcodes.trackUserAction({
  tag: 'document:delete',
  severity: 'high',
  status: true,
  metadata: { documentId: 'doc_123' },
});

Failed action with error


await transcodes.trackUserAction(
  {
    tag: 'payment:process',
    severity: 'high',
    status: false,
    error: 'Payment gateway timeout',
    metadata: { amount: 99.99 },
  },
  { webhookNotification: true }
);

Require authentication


// Redirects to Transcodes Auth if user not authenticated
await transcodes.trackUserAction(
  { tag: 'sensitive:action', severity: 'medium' },
  { requireAuth: true }
);

Skip auth (fire-and-forget only when signed in)


await transcodes.trackUserAction(
  { tag: 'analytics:view', severity: 'low' },
  { requireAuth: false }
);

Common Tags

Tag Pattern	Example Use Case
`user:login`	Member login event (example tag)
`user:register`	New member registration (example)
`user:logout`	Member sign-out (example tag)
`document:create`	Document created
`document:delete`	Document deleted
`payment:*`	Payment-related actions

Redirect API - Authentication redirects
Token API - Auth state
Audit logs guide — Console, webhooks, severity