Vaults API v1

Overview

Vaults are encrypted containers for storing sensitive data. Unlike Sparks (which are ephemeral and read-once), Vaults provide persistent storage that you can access repeatedly.

Key Concepts

Vault Lifecycle

Working with vaults follows this flow:

1. Create: Create a vault and receive the VMK (save it securely!)
2. Unseal: Provide the VMK to get a temporary VAT (1-hour default, up to 24 hours)
3. Read/Write: Use the VAT to create, read, update, or delete Ingots
4. Seal: (Optional) Manually seal to invalidate all VATs, or let them expire

# 1. Create a vault
curl -X POST https://api.sparkvault.com/v1/vaults \
  -H "X-API-Key: sv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Secrets"}'
# Returns: vault_id and vmk (SAVE THE VMK!)

# 2. Unseal the vault to get a VAT
curl -X POST https://api.sparkvault.com/v1/vaults/{vault_id}/unseal \
  -H "X-API-Key: sv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"vmk": "YOUR_VMK_HERE"}'
# Returns: vat (valid for 1 hour by default, up to 24 hours)

# 3. Create an ingot (upload data)
curl -X POST https://api.sparkvault.com/v1/vaults/{vault_id}/ingots \
  -H "X-API-Key: sv_live_xxx" \
  -H "X-Vault-Access-Token: YOUR_VAT" \
  -H "Content-Type: application/json" \
  -d '{"name": "config.json", "size_bytes": 1024}'
# Returns: forge_url for upload

# 4. Upload file to Forge with tus protocol
# Use the ISTK from forge_url as X-ISTK when creating the tus upload session

Create Vault

curl -X POST https://api.sparkvault.com/v1/vaults \
  -H "X-API-Key: sv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Secrets"}'

{
  "data": {
    "vault_id": "vlt_abc123def456...",
    "name": "Production Secrets",
    "vmk": "X9k2P8mQ7vH5nL3wR6tY...",
    "vmk_warning": "SAVE THIS KEY! SparkVault cannot recover it if lost. Store securely.",
    "created_at": 1702000000
  }
}

List Vaults

Get Vault

Update Vault

Unseal Vault

curl -X POST https://api.sparkvault.com/v1/vaults/vlt_abc123/unseal \
  -H "X-API-Key: sv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"vmk": "X9k2P8mQ7vH5nL3wR6tY..."}'

{
  "data": {
    "vat": "vat_xyz789...",
    "vault_id": "vlt_abc123def456...",
    "issued_at": 1702000000,
    "expires_at": 1702003600,
    "ttl_seconds": 3600,
    "warning": "Store this VAT securely. Required for all Ingot operations until expiration."
  }
}

Delegated Vault Access Keys (DVAKs)

DVAKs let vault admins delegate unseal access without sharing the VMK. A DVAK is used in place of the VMK in the Unseal Vault request body: the API recovers the VMK server-side and mints a VAT whose access level (read or read_write) is inherited from the DVAK. The full DVAK token is shown once at creation; afterwards only its last 4 characters are visible.

Create DVAK

# Issue a read-only DVAK to a teammate
curl -X POST https://api.sparkvault.com/v1/vaults/vlt_abc123/dvaks \
  -H "X-API-Key: sv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"vmk": "X9k2P8mQ7vH5nL3wR6tY...", "dvak_type": "user", "authorized_user_id": "usr_def456", "access_level": "read"}'

# The teammate unseals with the DVAK instead of the VMK
curl -X POST https://api.sparkvault.com/v1/vaults/vlt_abc123/unseal \
  -H "X-API-Key: sv_live_yyy" \
  -H "Content-Type: application/json" \
  -d '{"vmk": "dvak_kQ8n...w2Xz"}'

List DVAKs

Revoke DVAK

Seal Vault

curl -X POST https://api.sparkvault.com/v1/vaults/vlt_abc123/seal \
  -H "X-API-Key: sv_live_xxx"

(204 No Content)

Delete Vault

curl -X DELETE https://api.sparkvault.com/v1/vaults/vlt_abc123 \
  -H "X-API-Key: sv_live_xxx" \
  -H "X-Confirm-Name: Production Secrets"

{
  "data": {
    "message": "Vault deletion enqueued; cascade will run asynchronously",
    "vault_id": "vlt_abc123def456...",
    "started_at": 1702000000
  }
}

Ingot Operations

Once a vault is unsealed, you can create, read, update, and delete Ingots (encrypted data objects). SparkVault supports two types of ingots:

See the Ingots API Documentation for complete details on creating, reading, updating, and deleting ingots.

Folders

Folders provide hierarchical organization within a vault. All folder operations require an unsealed vault: include a valid VAT in the X-Vault-Access-Token header. A read-only VAT (minted from a read DVAK) can list and read folders but cannot create, modify, or delete them (403 FORBIDDEN).

• Folder names: max 255 characters; names starting with _ are reserved for system folders.
• Duplicate names within the same parent return 409 CONFLICT.
• Maximum nesting depth: 20 levels (enforced across the whole subtree when moving folders).
• System folders cannot be modified, deleted, or used as parents.

Create Folder

List Folders

Get Folder

Update Folder

Delete Folder

List Folder Contents

Vault Sharing

Vault sharing is the vault-level switch for secure public ingot sharing. Enabling it creates a system DVAK stored encrypted on SparkVault servers, so shared ingots can be decrypted for recipients without your SVMK or AMK. Per-ingot sharing controls (visibility, invitations) are documented on the SparkLinks API.

Get Sharing Configuration

Enable Sharing

Update Sharing Configuration

Disable Sharing

Upload Portal & Widget

Each vault has two optional public upload channels: the hosted Upload Portal (a page at files.sv for external users) and the embeddable Upload Widget (drop-zone in your own site via the JavaScript SDK). Enabling a channel mints its own system DVAK; encryption keys are derived server-side and only the ISTK reaches the browser. The VMK and VAK never leave the server. Public uploaders can add files but cannot retrieve them.

To embed the widget, see the JavaScript SDK guide: Use Case: Accept Secure File Uploads.

Get Upload Configuration

Update Upload Configuration

Enable / Disable the Upload Portal

curl -X POST https://api.sparkvault.com/v1/vaults/vlt_abc123/upload/portal/enable \
  -H "X-API-Key: sv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"vmk": "X9k2P8mQ7vH5nL3wR6tY..."}'

{
  "data": {
    "vault_id": "vlt_abc123def456...",
    "upload_portal_enabled": true,
    "enabled_at": 1702000000,
    "portal_url": "https://files.sv/in/abc123def456"
  }
}

Enable / Disable the Upload Widget

Access Log Retention

Configure how long access logs are retained for shared ingots in a vault. Logs count against your pooled storage (see pricing).

Get Access Log Retention

Update Access Log Retention

curl -X PUT https://api.sparkvault.com/v1/vaults/vlt_abc123/access-log-retention \
  -H "X-API-Key: sv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"access_log_retention_seconds": 31536000}'

{
  "data": {
    "vault_id": "vlt_abc123def456...",
    "access_log_retention_seconds": 31536000,
    "updated_at": 1702000000
  }
}

Usage

Vault operations are covered by your seat subscription. Storage and bandwidth consumption is tracked against the pool included with your plan. There are no per-operation charges. For subscription tiers and capacity blocks, see the pricing page.

For ingot transfer usage, see the Ingots API Documentation.

Error Reference