Audit Logs v1

Overview

SparkVault records security-relevant activity in a unified audit log. Every entry captures what happened (event_type), when (timestamp), who did it (actor_id), and from where (ip_address, user_agent), plus event-specific metadata. Events are partitioned into four scopes, each with its own list endpoint:

Entries are returned newest-first with signed cursor pagination. Account and integration entries are stored in plaintext. Vault and ingot entry metadata is encrypted at rest with AES-256-GCM under a key derived (HKDF) from the vault's Vault Access Key (VAK) when the event is recorded through an unsealed session. It can only be decrypted with a valid Vault Access Token. Events recorded outside a vault session (such as retention_changed) store their metadata in plaintext.

Entry Fields

Audit logs answer who did what, and when. For usage aggregates and analytics dashboards, see Reporting.

Event Types

Each scope has its own set of event types. The account, vault, and ingot list endpoints return the full valid set for their scope in the response's event_types field, so you can build filters without hardcoding the lists below.

Account Events

The account-scope event_types response set also includes platform-admin event types (admin_impersonate, admin_account_deleted, admin_status_changed, admin_pricing_updated, admin_blocklist_source_toggled, admin_blocklist_domain_added, admin_blocklist_domain_removed). These are recorded only under the SparkVault platform admin account, so your own audit logs will never contain them.

Vault Events

Ingot Events

Integration and Product Events

Integration-scope event types are free-form strings: integrations and products define their own. Common patterns:

Pagination and Filtering

All list endpoints share the same cursor-based pagination and filtering contract:

• Ordering: entries are returned newest-first; timestamp is epoch seconds.
• has_more / next_cursor: next_cursor is present only when has_more is true. Keep requesting with ?cursor= until has_more is false.
• Signed cursors: cursors are HMAC-signed per account and bound to the exact audit scope they were minted for. A tampered cursor, a cursor from another account, or a cursor replayed against a different scope returns 400 VALIDATION_ERROR.
• Filtered pages can run short: with an event_types filter, a page may contain fewer than limit entries (even zero) while has_more is still true. Always page by has_more, not by page size.

Account Audit Logs

curl "https://api.sparkvault.com/v1/audit-logs?limit=2&event_types=login,login_failed" \
  -H "X-API-Key: sv_live_xxx"

{
  "data": {
    "entries": [
      {
        "timestamp": 1702000600,
        "event_type": "login",
        "actor_id": "usr_abc123...",
        "actor_type": "user",
        "actor_display": "admin@example.com",
        "ip_address": "203.0.113.7",
        "user_agent": "Mozilla/5.0...",
        "metadata": null
      },
      {
        "timestamp": 1702000000,
        "event_type": "login_failed",
        "actor_id": null,
        "ip_address": "198.51.100.23",
        "user_agent": "Mozilla/5.0...",
        "metadata": null
      }
    ],
    "count": 2,
    "has_more": true,
    "next_cursor": "eyJrZXkiOnsi...",
    "event_types": ["user_invited", "user_removed", "user_role_changed", "..."]
  }
}

Integration and Product Audit Logs

Every installed integration and every product keeps its own event stream, addressed by its slug. The API calls this scope apps. Integration-scope entries record timestamp, event_type, metadata, and app_slug. They carry no actor or IP fields.

curl "https://api.sparkvault.com/v1/audit-logs/apps/slack?limit=25" \
  -H "X-API-Key: sv_live_xxx"

{
  "data": {
    "entries": [
      {
        "timestamp": 1702000000,
        "event_type": "slack_connected",
        "metadata": null,
        "app_slug": "slack"
      }
    ],
    "count": 1,
    "has_more": false,
    "app_slug": "slack"
  }
}

curl -X POST https://api.sparkvault.com/v1/audit-logs/apps \
  -H "X-API-Key: sv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "app_slug": "hubspot",
    "event_type": "export_completed",
    "metadata": { "record_count": 42 }
  }'

{
  "data": {
    "logged": true,
    "app_slug": "hubspot",
    "event_type": "export_completed"
  }
}

Vault Audit Logs

This endpoint requires the X-Vault-Access-Token header with a valid VAT obtained by unsealing the vault. Entry metadata is stored encrypted and is decrypted transparently with the VAK held by your VAT session. Vault-scope events cover the vault itself. Per-file events live on the per-ingot endpoint.

curl "https://api.sparkvault.com/v1/vaults/vlt_abc123/audit-logs?limit=25" \
  -H "X-API-Key: sv_live_xxx" \
  -H "X-Vault-Access-Token: vat_xyz789..."

{
  "data": {
    "entries": [
      {
        "timestamp": 1702000000,
        "event_type": "vault_unsealed",
        "actor_id": "usr_abc123...",
        "actor_type": "user",
        "actor_display": "admin@example.com",
        "ip_address": "203.0.113.7",
        "user_agent": "Mozilla/5.0...",
        "metadata": { "ttl_seconds": 3600 },
        "vault_id": "vlt_abc123..."
      }
    ],
    "count": 1,
    "has_more": false,
    "vault_id": "vlt_abc123...",
    "event_types": ["vault_renamed", "vault_settings_changed", "..."]
  }
}

Ingot Audit Logs

The per-ingot endpoint follows the same auth, pagination, and filtering contract as the vault endpoint above: X-Vault-Access-Token required, encrypted metadata decrypted via your VAT session, and a response carrying entries (each with vault_id and ingot_id), count, has_more, next_cursor, and the valid ingot-scope event_types. Full documentation lives on the Ingots page.

Retention

Every audit entry is written with an expiry and is removed automatically when it lapses. The default retention window is 90 days (7,776,000 seconds).

Each vault additionally carries a configurable access-log retention setting (GET/PUT /v1/vaults/{vault_id}/access-log-retention, see the Vaults docs) that governs how long ingot access events recorded through public sharing surfaces (public portal uploads and SparkLink downloads) are kept. Setting it to 0 (Disabled) turns that logging off entirely: no entries are written. The change itself is always recorded as a retention_changed vault event under the default window, so the configuration trail survives even when access logging is disabled.

Error Reference