# Audit project changes through automation

Read the shipped project audit feed while preserving privacy and attribution boundaries.

The preview Management API exposes project-scoped audit events with `management:audit:read`. Use it to
synchronize control-plane changes or drive review workflows, not as a runtime-event export.

For interactive organisation-wide investigation, use the console Activity surface.

## Resolve the project

Discover organisations and projects through Management reads and retain the stable project ID. Do not
derive project identity from a console slug that can change.

After a project transfer, current discovery follows the destination. Historical events retain their
recorded source-organisation attribution.

## Read a page

Audit pagination is one-based and uses `page` and `limit`:

```sh
curl \
  "https://api.featuregate.dev/v1/projects/$FEATUREGATE_PROJECT_ID/audit-events?page=1&limit=50" \
  -H "Authorization: Bearer $FEATUREGATE_MANAGEMENT_KEY"
```

The response includes `auditEvents`, `page`, `pageCount`, `pageSize`, and `totalCount`. `limit` can be
at most 100 under the current contract.

Do not implement cursor logic against this endpoint. Advance pages according to response metadata and
the generated reference.

## Synchronize safely

For periodic collection:

1. Request pages in order for the intended project.
2. Store stable event identity in the receiving system.
3. De-duplicate events already processed.
4. Tolerate a repeated page when a job retries.
5. Record collection checkpoints without storing the management key.
6. Reconcile page counts when events arrive during a long scan.

Do not rely only on timestamps. Events can share a timestamp and clock formatting can change during
downstream processing.

## Interpret events

Events can describe flag identity and configuration, targeting changes, key lifecycle, project
operations, and other project-scoped control-plane actions.

Actor and resource metadata are designed for safe audit use. Key events expose metadata and prefix,
not the raw one-time secret.

The endpoint is project-scoped. It does not provide the complete organisation feed for billing,
membership, account security, or unrelated projects.

## Privacy boundary

The audit feed does not expose:

- Raw runtime or management keys.
- Authorization headers or cookies.
- Request or response bodies.
- Evaluation context or user identifiers from context.
- Targeting attribute values.
- Resolved flag values.
- User agents or IP addresses.

Do not attempt to reconstruct exposure analytics from audit events. They record management actions,
not every hosted request or local SDK evaluation.

## Downstream storage

Store only fields needed by the receiving audit system. Apply access controls and retention matching
the source organisation's policy.

Keep the management key in a secret manager. Rotate it separately from runtime keys and remove it from
logs, traces, queue payloads, and dead-letter records.

## Failure handling

- `401`: rotate the invalid or revoked management key.
- `403`: check `management:audit:read`, project visibility, and organisation lifecycle.
- `429`: respect retry information and reduce collection pressure.
- `5xx`: retry page reads with bounded backoff and de-duplication.

Related pages: [Activity and audit history](/docs/operate/activity-and-audit),
[Management API overview](/docs/automation/management-api), and the generated
[audit endpoint reference](/docs/api/reference/management/projects/audit-events).