Admin
Exporting Audit Logs
Download, stream, or archive Alter audit events.
Credential access, provider calls, policy decisions, lifecycle changes, and administrative actions produce structured audit events. The developer portal supports filtered downloads, uncapped bulk jobs, telemetry mirroring, and continuous SIEM delivery. The CLI provides a paginated pull path for custom archives and ingestion pipelines.
What’s in an audit row
Section titled “What’s in an audit row”See Audit logs for the full field list. The short version per call:
- Timestamps, app and provider identifiers, response status, latency.
- Caller (key prefix, agent identity if applicable, free-form
callerattribution). - Principal (user / group / system / agent that owns the grant).
- Grant reference, kind, and data categories when present.
- Context (application-supplied tool name, run ID, thread ID).
- Reason (the human-readable explanation passed on the request).
- Outcome (success / policy denial / provider error / network error).
Sensitive headers are stripped. Audit rows and exports contain request and response metadata (including body sizes), not bodies. Request and response payload capture is a separate, opt-in diagnostic feature: captured bodies use the deployment’s configured size cap (64 KiB per body by default), record truncation, and expire under the configured payload-retention period. Captured payloads are never included in audit exports.
Export paths
Section titled “Export paths”1. Filtered export from the portal
Section titled “1. Filtered export from the portal”On an app’s Audit Logs page, select Export. Choose a date range of up to 365 days, select CSV, JSON, or NDJSON, and decide whether to apply the current view’s filters. The synchronous export contains the 50,000 most-recent matching events. If the cap is reached, the portal reports that the file was trimmed so the range or filters can be narrowed.
2. Bulk export from the portal
Section titled “2. Bulk export from the portal”On the Access & Requests tab, select Bulk export for a server-side job that writes every matching access or request event in the selected date range to a downloadable CSV or NDJSON artifact. Bulk exports have no row cap. The portal polls the job and presents a short-lived download link when it is complete. Bulk export requires export storage to be enabled on the deployment.
3. Pull via CLI
Section titled “3. Pull via CLI”PAT-authenticated automation can read the audit surface with dashboard_audit:read. For example:
alter audit list --since 30d --output jsonl > audit.ndjsonJSON list output returns a paginated envelope; JSONL writes one page of rows. A long-running collector is responsible for advancing --offset or the time window and persisting its own checkpoint.
4. Telemetry endpoint (OTLP)
Section titled “4. Telemetry endpoint (OTLP)”Under Settings → Audit & compliance → Telemetry endpoint (OTLP), configure a default organization collector or app-specific overrides. Alter mirrors audit events as OpenTelemetry spans to the configured OTLP/HTTP collector. This is a telemetry stream, not the compliance source; the authoritative audit trail remains in Alter.
5. SIEM destination (OCSF)
Section titled “5. SIEM destination (OCSF)”Configure a SIEM destination under Settings → Audit & compliance → SIEM export in the developer portal. Alter then continuously pushes the organization’s audit events to the SIEM’s HTTPS collector as newline-delimited OCSF 1.5.0 events (Splunk HEC and generic-webhook compatible). Authentication headers for the collector are stored encrypted.
Delivery is at-least-once: a per-destination cursor advances only after the collector acknowledges a batch, so a mid-delivery failure re-sends the batch. SIEMs deduplicate on metadata.uid (the audit event id). Repeated delivery failures dead-letter the destination — it is auto-disabled and surfaced in the portal, with the cursor preserved so re-enabling resumes without gaps.
OCSF event shape (SIEM destination)
Section titled “OCSF event shape (SIEM destination)”Each event delivered to a SIEM destination is an OCSF 1.5.0 API Activity record (class_uid 6003, category_uid 6). It carries identifiers and outcomes only — never tokens and never end-user PII. The identity mapping:
| OCSF field | Meaning |
|---|---|
metadata.version | 1.5.0 |
metadata.uid | Audit event id — the SIEM dedupe key |
time | Event time (epoch milliseconds) |
activity_name | The action performed (for example token.retrieved) |
status_id / status | Outcome enum + caption (Success / Failure / Unknown) |
status_detail | Granular result (success / failure / denied / error) |
severity_id | 1 informational, 3 failure, 4 explicit denial |
actor.user | The acting principal — the AI agent (type "AI Agent") when one authenticated, otherwise the registered caller (type "Other"); absent when the event has no principal |
actor.app_name / actor.app_uid | The application that made the call |
actor.session.uid | The API key that established the session |
resources[] | The end user the call acted for (type "app_user") |
unmapped | Alter correlation metadata (trace and span ids, policy decision) that has no first-class OCSF field |
Display names (actor.app_name, actor.user.name) are the names configured in the portal and resolve only within the owning organization; a name that cannot be resolved degrades to the uid alone.
Retention
Section titled “Retention”Audit retention is an organization-wide, admin-only control under Settings → Audit & compliance → Audit retention. The plan defines a minimum and, when applicable, a maximum; the organization override can only extend the plan minimum. Clearing the override returns to the plan minimum. The default plan fallback is 365 days.
A compliance hold prevents matching records from being deleted regardless of the normal retention window. For a separate long-term archive, ingest CLI or bulk-export output into the organization’s storage system.