- Sells as: the
audit-log product (a product-scoped API key). This capability has no separate product-face contract — its public product route reuses the capability contract below; see the Edge route table's Product face row.
Append-only, org-scoped SOC2 audit-trail capability — one immutable write API + a forensic-replay query API, so products stop each owning a private admin-audit table and instead EMIT audit records to ONE shared, queryable compliance backend. Records are IMMUTABLE (no update/delete API — retention purge is bulk housekeeping past the legal window). I4: own Postgres store, never a product Mongo.
- Group: Governance & platform
- Contract:
contracts/audit-log/v1/openapi.yaml
- Console: Manage the
audit-log product in the console →
- Runbook: operational checklist for
audit-log — internal (Vagary Labs ops; not part of this public site): docs/runbooks/capability-operations.md#audit-log
- Public base:
https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
- Auth: a product API key (
vgk_…) issued from the console — Authorization: Bearer vgk_…
- Product face (customer-keyed):
https://api.vagarylabs.com/product/v1/audit/events
Edge route table
The routes this capability actually serves on the public edge — live-synced from GET https://api.vagarylabs.com/product/v1/_meta/catalog (snapshot v1). The metric is the request-granularity billing counter; the scope is the key permission required.
Product face (customer-keyed)
| Method | Path | Metric | Scope |
|---|
POST | /product/v1/audit/events | audit_events | write |
Endpoints
| Method | Path | Summary |
|---|
POST | /v1/audit/events | Record one immutable audit event |
GET | /v1/audit/events | The caller org's audit trail, newest-first, optionally filtered (SOC2 forensic replay) |
GET | /health | liveness |
GET | /metrics | Prometheus |
Schemas
Outcome
SOC2 outcome — the UNION of the platform set {success,failure,denied,partial} and the voice audit_logs status set {allowed,denied,error}. An unknown value is normalized to "success" on write (platform parity), never rejected.
AppendRequest
| Field | Type | Description |
|---|
organization_id | string | product-tier tenant (I6); anti-spoof-verified against the token |
action | string | canonical '<resource>.<verb>' event name, e.g. 'user.unlock' |
resource_type | string | the affected resource class, e.g. 'user' |
resource_id | string | primary id of the affected row (if any) |
actor_id | string | the acting user id; omit/null for system/webhook actors |
details | object | structured context (stored raw JSONB) |
outcome | object | |
source_ip | string | caller IP for forensic replay |
request_id | string | correlation id across log streams |
occurred_at | string | event time; defaults to server now() if omitted |
AuditEvent
| Field | Type | Description |
|---|
id | string | |
organization_id | string | |
actor_id | string | |
action | string | |
resource_type | string | |
resource_id | string | |
details | object | |
outcome | object | |
source_ip | string | |
request_id | string | |
occurred_at | string | |
QueryResult
| Field | Type | Description |
|---|
events | array | |
count | integer | |
Error
| Field | Type | Description |
|---|
error | string | stable machine code (e.g. validation_error, not_found, unauthorized) |
reason | string | human-readable one-line explanation (no secrets/PII) |
detail | object | |
request_id | string | |
Generated by scripts/gen-capability-docs.py from contracts/audit-log/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page. The Edge route table section is synced from the live edge catalog snapshot (v1) — re-sync with python3 scripts/sync-edge-catalog.py.