Audit log

The audit log is the organization’s tamper-resistant record of privileged actions. Unlike the activity feed, it is admin-only and records the security facts: actor, IP, user agent and structured metadata.

	Activity feed	Audit log
Who can read	anyone with repository access	audit.read — ADMIN, OWNER
Purpose	understand the work	answer “who did this, from where?”
Records IP / user agent	no	yes
Reachable by an API token scope	yes	no — session-authenticated roles only
Plan	all plans	Team and Business

Note

No token scope grants audit.read. A leaked CI token cannot read your audit trail — by design. Reading it requires a signed-in ADMIN or OWNER.

Reading it

Organization settings → Audit log, or:

curl -sS "https://cavsnode.com/api/v1/organizations/acme-ai/audit" \
  -H "Authorization: Bearer $CAVS_TOKEN"

Response

{
  "events": [
    {
      "id": "3f9a…",
      "organization_id": "0a11…",
      "actor_id": "77bc…",
      "action": "token.created",
      "resource_type": "token",
      "resource_id": "6f1a…",
      "ip_address": "203.0.113.7",
      "user_agent": "Mozilla/5.0 …",
      "metadata": { "name": "github-actions/vision-build", "kind": "CI" },
      "created_at": "2026-07-28T12:00:04Z"
    }
  ]
}

Caution

The endpoint returns the 100 most recent events and takes no filter or paging parameters. For long-term retention, export on a schedule (below) rather than relying on the API as an archive.

What gets recorded

Area	Actions
Organization	organization.updated, organization.deleted
Members	member.invited, member.removed, member.role_changed, member.left, organization.member.joined
Invitations	invitation.revoked, invitation.link_regenerated
Tokens	token.created, token.revoked
Repositories	repository.created, repository.updated, repository.deleted, repository.push, repository.index
Repository access	repository.member.invited, repository.member.joined, repository.member.upserted, repository.member.removed, repository.invitation.revoked
Releases & snapshots	repository.release.updated, repository.snapshot.requested
Lineage	repository.graph.edge.created, repository.graph.edge.deleted
Storage	storage.connection.created, .updated, .tested, .removed; storage_group.created, .updated, .deleted
Webhooks	webhook.created, webhook.updated, webhook.deleted
Billing	billing.checkout_started, billing.subscription_updated, billing.byos_addon_updated

Each carries the metadata relevant to it — a push records its generation and object count, a token creation records the name and kind, a role change records the old and new roles.

Not in the audit log

Data-plane reads are not audited per byte — that would mean an audit write per download. What is recorded is the authorization: pushes appear as repository.push, and per-object download counters are maintained on the objects themselves. If you need per-download attribution, the usage ledger has a per-event record with the acting user.

Questions it answers

export API=https://cavsnode.com/api/v1
export H="Authorization: Bearer $CAVS_TOKEN"
AUDIT="$API/organizations/acme-ai/audit"

# Who created tokens recently?
curl -sS "$AUDIT" -H "$H" | jq '.events[] | select(.action == "token.created")'

# Everything one actor did
curl -sS "$AUDIT" -H "$H" | jq --arg a "$USER_ID" '.events[] | select(.actor_id == $a)'

# Anything from an unexpected address
curl -sS "$AUDIT" -H "$H" | jq -r '.events[] | "\(.created_at)\t\(.ip_address)\t\(.action)"'

# Deletions
curl -sS "$AUDIT" -H "$H" | jq '.events[] | select(.action | test("deleted|removed|revoked"))'

Exporting for retention

Since the endpoint keeps only the last 100 events, archive them somewhere durable if you have a retention obligation. Poll frequently enough that you never miss more than 100 events between runs — hourly is plenty for most organizations.

audit-export.sh

#!/usr/bin/env bash
set -euo pipefail

ORG=acme-ai
OUT="audit/$(date -u +%Y-%m-%d).jsonl"
mkdir -p audit

curl -sS --fail-with-body \
  "https://cavsnode.com/api/v1/organizations/$ORG/audit" \
  -H "Authorization: Bearer $CAVS_ADMIN_TOKEN" \
  | jq -c '.events[]' >> "$OUT"

# De-duplicate by event id, since consecutive polls overlap.
sort -u -t'"' -k4,4 "$OUT" -o "$OUT"

Caution

This needs a session-authenticated ADMIN/OWNER credential — an API token can’t read audit. In practice that means running the export interactively or with a Firebase service credential, not from a CI token.

Investigating an incident

1. Contain first. Revoke the suspect token or remove the member. Investigation is second.
2. Pull the audit log immediately, before it rolls past 100 events, and save it.
3. Filter by actor_id for everything that actor touched.
4. Cross-check ip_address against expected ranges — and against the token list’s last-used IP.
5. Check repository.push and repository.deleted entries for data changes.
6. Check token.created — a common escalation is minting a new token before doing anything visible.
7. Check storage.connection.updated — repointing storage is a quiet way to redirect data.
8. Quote the request_id from any related API error when you contact support.

Availability

The audit log is a Team and Business plan feature (features.audit_log). Free and Developer organizations still have the activity feed and per-token last-used data.

Next

• API tokens — last-used data, revocation.
• Security model — what we store and how it’s protected.
• Usage & metering — the per-event ledger.