---
title: "Audit events"
description: "The sanitized organization audit inventory available in the dashboard and v1 API."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.stackship.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit events

StackShip writes audit evidence inside product transactions for security-
relevant mutations. The dashboard and
`GET /v1/audit-events` expose a sanitized, organization-scoped inventory.

## Returned fields

Each API item contains:

| Field | Meaning |
| --- | --- |
| `object` | Always `audit_event` |
| `actor_id` | Opaque identity of the actor |
| `action` | Stable product action name |
| `target_type` | Kind of object affected |
| `target_id` | Opaque target identity, or `null` |
| `request_id` | Request correlation identity |
| `created_at` | RFC 3339 event time |

The public response omits raw IP addresses, user-agent strings, credentials,
variable values, state content, plan content, repository content, and internal
capabilities.

## Scope and completeness

Audit reads use the active organization from the verified session.
The dashboard requests only the newest bounded organization page. An empty page
means no events were returned in that page; it is not a statement that no older
evidence exists.

The API response carries continuation only in `meta.page.next_cursor`. Pass a
non-null value back as the next request's `cursor`. Audit records do not expose
per-record cursors, and a timestamp is not a valid cursor. The opaque token
includes the internal event identity as a tie-breaker so events committed at
the same instant are returned exactly once. Invalid or audit-mismatched tokens
return `400 AUDIT_LIST_CURSOR_INVALID`.

The launch API does not provide customer-configured export destinations,
retention controls, webhook delivery, or a cryptographic verification endpoint.
Operators retain database and object evidence according to the production
runbooks.

## Examples of audited behavior

The implementation records evidence for actions including:

- project, workspace, variable, policy, source, credential, and token
  mutations;
- run creation and human decisions;
- interrupted-apply recovery, recovery-fence advancement, and emergency-state
  publication;
- state publication and raw state download;
- source ingestion and configuration commitment; and
- versioned launch-control changes.

Some operational events remain internal because their payload is not safe for
the customer response. The absence of an internal field from `/v1/audit-events`
does not make a security decision unaudited.

## Related pages

- [Governance](/governance)
- [Run approvals](/runs/approvals)
- [v1 REST API](/automation/api)

Source: https://docs.stackship.run/governance/audit/index.mdx