Audit log

Every action on your account lands in an append-only audit log: API key lifecycle, session events, profile changes, subscription changes, MFA enrollment, webhook config, team member changes, and admin-recorded support notes. Customers can read the log programmatically for compliance + monitoring, and export the complete history per the GDPR Article 20 right to data portability.

List

GET /v1/account/audit-log

Query parameters:

• limit — page size, 1-100; default 50.
• cursor — pagination token from a prior page’s next_cursor.
• action — filter to a single action name (see catalog below).

Response (200):

{
  "data": [
    {
      "id": "<uuid>",
      "account_id": "acc_<uuid>",
      "actor_type": "customer",
      "actor_account_id": "acc_<uuid>",
      "actor_key_id": "key_<uuid>",
      "action": "api_key.minted",
      "target_resource_id": "key_<new-key-uuid>",
      "payload": { "name": "production", "scopes": ["read", "write"] },
      "ip_address": null,
      "user_agent": null,
      "timestamp": "2026-05-09T22:30:00.000Z"
    }
  ],
  "next_cursor": "<opaque-cursor>"
}

Both account_id and actor_account_id carry the public acc_ prefix on the wire (matches the format GET /v1/account/me returns). The bare row id is a UUID (no prefix). actor_key_id is key_<key-uuid> for API-key calls and null for web-session calls (dashboard actions record no key id); the wire value is always key_-prefixed or null.

next_cursor is null when there are no more pages.

The actor_type enum:

• customer — a human action through the dashboard or an API call with a customer-issued bearer.
• system — an automated event (Stripe-driven tier changes, email verification, scheduled-job side-effects).
• staff — a Driftstack support-team action against the account (rare; recorded for transparency).

actor_account_id is the calling account for customer actions — which is NOT necessarily the same as the row’s account_id. When a team member acts on the owner’s account via the X-Driftstack-Account header , the entry lands on the owner’s audit log (account_id = acc_<owner>) but actor_account_id records the member who performed the action (acc_<member>). Owners reading their audit log can therefore see “who on my team did what” without separate correlation. Self-action audit entries have actor_account_id == account_id.

actor_key_id is key_<key-uuid> for API-key calls and null for web-session calls (the dashboard audit emitters record no key id). It is also null for system and staff events.

ip_address and user_agent (top-level fields on the entry) are populated with the real caller network identity ONLY on rows that are self-caused — i.e. the row’s actor_account_id is either null or equal to account_id (a customer acting directly on their own account: profile/API-key/BYOK-key/web-session/email- preference actions, etc.). GDPR Article 15 (right of access to own data) covers a customer seeing their own login/device IPs this way.

Both fields are redacted to null — regardless of who is reading — whenever the row is cross-account-caused: its actor_account_id records an account DIFFERENT from account_id. This covers a Driftstack staff member’s admin.support_note / admin.refund_recorded note (landed on the customer’s log with the staff member’s IP), and any future action a team member performs on an owner’s account via X-Driftstack-Account once that write path records actor_account_id. The redaction is per-row and independent of the reader: an owner self-reading their OWN log still gets null on a cross-account-caused row, exactly as a team member reading the owner’s log does.

Caveat: the auth-flow audit events (account.email_verified, account.login, account.logout, account.password_changed) currently store issued_from_ip + user_agent inside payload in addition to (not instead of) the row-level columns above. On a self-caused row those payload fields are visible to the owner (same Article-15 rationale). On a cross-account-caused OR cross-account-READ row (a team member using X-Driftstack-Account to view the owner’s log) the server scrubs issued_from_ip / source_ip / ip_address / user_agent / issued_user_agent out of payload in addition to nulling the top-level ip_address / user_agent fields — no data backfill needed since the scrub runs at read/export serialization time.

Action catalog

Filter examples

Latest 25 logins:

GET /v1/account/audit-log?action=account.login&limit=25

All MFA lifecycle events:

GET /v1/account/audit-log?action=account.mfa_enrolled
GET /v1/account/audit-log?action=account.mfa_disabled
GET /v1/account/audit-log?action=account.recovery_code_used

(Multi-action filtering in a single call isn’t supported; the dashboard’s filter dropdown calls separately and merges client-side when it needs a composite view.)

Walk every entry:

let cursor = null;
while (true) {
  const url = '/v1/account/audit-log?limit=100' + (cursor ? `&cursor=${cursor}` : '');
  const page = await fetch(url, { headers: { authorization: `Bearer ${KEY}` } }).then((r) => r.json());
  for (const entry of page.data) console.log(entry.timestamp, entry.action);
  if (!page.next_cursor) break;
  cursor = page.next_cursor;
}

Payload reference

Several action types carry typed payload fields the customer dashboard renders inline. Consumers parsing the JSON should expect the following shapes:

// account.login — password / MFA sign-ins
{ "method": "password" | "mfa_totp" | "mfa_recovery" }

// account.login — OAuth sign-ins (no method field)
{ "kind": "oauth_callback", "provider": "<provider>", "session_id": "<web-session-id>" }

// account.recovery_code_used
{ "remaining": <integer 0-9> }

// profile.created — three creation paths
{ "name": "<profile-name>", "archetype": "<archetype-slug>" }                          // direct create
{ "name": "...", "archetype": "...", "cloned_from": "profile_<uuid>" } // clone
{ "name": "...", "archetype": "...", "restored_from_snapshot": "psnap_<uuid>" } // restore

// webhook_endpoint.secret_rotated
{
  "new_secret_prefix": "whsec_<first-12>",
  "old_secret_prefix": "whsec_<first-12>",
  "grace_expires_at": "2026-05-10T00:00:00.000Z"
}

// team.member_invited
{ "invitee_email": "<invited-address>", "role": "admin" | "member" }

// subscription.tier_changed
{ "from": "<tier-slug>", "to": "<tier-slug>" }

// api_key.minted
{ "name": "<key-name>", "scopes": ["read", "write"] }

Other action types carry minimal payloads (often just one or two contextual fields — e.g. account.logout carries the web session_id; account.password_changed carries via: "password_reset" plus the network-identity fields noted in the caveat above). Consumers should default-handle unknown payload shapes gracefully; new fields are additive.

Export

GET /v1/account/audit-log/export?format=csv (or format=json)

Returns the FULL audit-log history for the calling account as a single download (no pagination). Used for GDPR Article 20 portability — customer takes their compliance record off the platform.

Response headers:

• Content-Type — text/csv or application/json
• Content-Disposition — attachment; filename="driftstack-audit-log-<YYYY-MM-DD>.{ext}" (the date is the export day, UTC)

Cap: 10,000 rows per file. Older entries remain accessible via the paginated read endpoint above.

CSV columns (in order): timestamp, action, actor_type, actor_account_id, actor_key_id, target_resource_id, ip_address, user_agent, payload. The payload column is the JSON-encoded payload field (stringified + escaped per CSV rules).

JSON envelope:

{
  "generated_at": "2026-05-09T18:00:00Z",
  "account_id": "acc_abc",
  "row_count": 142,
  "truncated": false,
  "data": [
    /* up to 10,000 audit-log entries — same shape as the read endpoint */
  ]
}

The truncated flag is true when the row count hit the 10,000-row ceiling and older entries weren’t included. Customers needing the full history should narrow the date window or paginate via the read endpoint above.

SDK examples (JSON branch only)

The SDKs expose the JSON branch only — CSV download is browser-driven and not useful through a typed SDK call. Customers wanting CSV hit the URL directly with their bearer.

const dump = await client.auditLog.export();
console.log(dump.row_count, dump.truncated);
for (const entry of dump.data) {
  console.log(entry.timestamp, entry.action, entry.target_resource_id);
}

dump = client.audit_log.export()
print(dump["row_count"], dump["truncated"])
for entry in dump["data"]:
    print(entry["timestamp"], entry["action"])

dump, _ := client.AuditLog.Export(ctx)
fmt.Println(dump.RowCount, dump.Truncated)
for _, entry := range dump.Data {
    fmt.Println(entry.Timestamp, entry.Action)
}

Auth + scoping

Both endpoints require a customer bearer (API key OR web session) with the granular read:audit scope. A broad read key — or an account_owner key — satisfies it (broad scopes satisfy their granular counterparts), so a key minted with just read:audit, read, or account_owner all work. The X-Driftstack-Account header is honored for team scopes: a member with read access on the team owner sees the OWNER’s audit log when the header is set (the scope check stays on the caller’s own key).

Errors