Authentication v1

Overview

SparkVault supports two authentication methods:

API Key Authentication

API keys provide simple, persistent authentication for server-side integrations. Create an API key from the API Keys page and include it in the X-API-Key header.

curl https://api.sparkvault.com/v1/sparks \
  -H "X-API-Key: sv_live_abc123xyz789..."

API Key Format

API keys follow a consistent format:

• sv_live_...: Production keys (live data)

Example: Creating a Spark with an API key

curl -X POST https://api.sparkvault.com/v1/sparks \
  -H "X-API-Key: sv_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "super_secret_password_123"
  }'

Managing API Keys Programmatically

API keys can be managed in the app at app.sparkvault.com/api/keys, or programmatically with the endpoints below. All three endpoints require authentication (JWT or API key). Creating and revoking keys additionally require an admin or owner role. Non-admin users receive 403 FORBIDDEN.

curl -X POST https://api.sparkvault.com/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD pipeline",
    "expires_in_days": 90
  }'

{
  "data": {
    "api_key_id": "key_abc123...",
    "api_key": "sv_live_abc123xyz789...",
    "key_preview": "sv_live_ab...z789",
    "name": "CI/CD pipeline",
    "created_at": 1783036800,
    "expires_at": 1790812800,
    "warning": "Store this API key securely. It will not be shown again."
  }
}

JWT Token Authentication

JWT tokens are used for user session management in browser-based applications. SparkVault uses the Identity Product as an OIDC provider for user authentication. After successful authentication via Identity, you'll receive SparkVault session tokens.

curl https://api.sparkvault.com/v1/sparks \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Token Types

User Authentication Flow

SparkVault uses an OIDC (OpenID Connect) flow with the Identity Product for user authentication. This provides passwordless login via passkeys, magic links, social login, and more.

Flow Overview

1. Initiate Login: Redirect user to Identity Product with PKCE challenge
2. User Authenticates: Via passkey, magic link, or social login
3. Callback: Identity Product redirects back with authorization code
4. Token Exchange: Exchange code for SparkVault session tokens
5. Registration (New Users): Complete profile setup if needed

Session Endpoints

curl -X POST https://api.sparkvault.com/v1/auth/identity/token \
  -H "Content-Type: application/json" \
  -d '{
    "code": "auth_code_from_identity_product",
    "code_verifier": "your_pkce_code_verifier"
  }'

{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
    "user": {
      "user_id": "usr_abc123...",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "admin"
    },
    "account": {
      "account_id": "acc_xyz789...",
      "organization_name": "Acme Corp",
      "status": "active"
    }
  }
}

curl -X POST https://api.sparkvault.com/v1/auth/identity/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJhbGciOiJFZDI1NTE5..."}'

{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
    "user": {
      "user_id": "usr_abc123...",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "admin"
    },
    "account": {
      "account_id": "acc_xyz789...",
      "organization_name": "Acme Corp",
      "status": "active"
    }
  }
}

curl -X POST https://api.sparkvault.com/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJSUzI1NiIs..."}'

{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "session_type": "full",
    "user": { "user_id": "usr_abc123..." },
    "account": { "account_id": "acc_xyz789..." }
  }
}

curl -X POST https://api.sparkvault.com/v1/auth/logout \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJSUzI1NiIs..."}'

(204 No Content)

Vault Access Tokens (VAT)

Vault Access Tokens are special, short-lived tokens required for reading and writing data in encrypted vaults. They are obtained by "unsealing" a vault with the key you hold: its Vault Master Key (VMK), or a DVAK token issued for it.

# First, unseal the vault to get a VAT
curl -X POST https://api.sparkvault.com/v1/vaults/vlt_abc123/unseal \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"vmk": "YOUR_VAULT_MASTER_KEY"}'

# Holding a delegated key instead? Send it as dvak_token
curl -X POST https://api.sparkvault.com/v1/vaults/vlt_abc123/unseal \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"dvak_token": "dvak_kQ8n...w2Xz"}'

# Then use the VAT for ingot operations
curl https://api.sparkvault.com/v1/vaults/vlt_abc123/ingots \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "X-Vault-Access-Token: vat_xyz789..."

Authentication Errors

Security Best Practices

API Keys

• Generate separate API keys for each integration or service
• Use descriptive names to identify key purpose
• Rotate keys periodically (every 90 days recommended)
• Revoke keys immediately if compromised
• Never commit keys to version control. Use environment variables.

JWT Tokens

• Dashboard browsers keep access tokens in memory and refresh only through the host-locked HttpOnly cookie
• Native and server clients keep refresh credentials in their platform secure store, never localStorage
• Implement automatic token refresh before expiry
• Native and server clients atomically persist each rotated response token before using it again
• Clear the browser access token immediately when logout starts; the API revokes and clears the refresh cookie
• Retry transient 503 responses; redirect to login only when refresh returns an authentication failure

PKCE Security

• Always use S256 code challenge method (never plain)
• Generate cryptographically random code verifiers (32+ bytes)
• Store PKCE parameters in sessionStorage (not localStorage)
• Validate the state parameter to prevent CSRF attacks

General

• Always use HTTPS. Never send credentials over plain HTTP.
• Implement proper error handling for auth failures
• Log authentication events for security monitoring
• Use passkeys where possible for phishing resistance