Skip to main content

​
Overview

sovseal uses a cryptographically blinded authentication mechanism. Because we operate on a zero-knowledge threat model, the server never learns your raw encryption keys. Authentication keys are mapped to projects and used exclusively to authenticate Layer-A API request headers.

​
Token Types & Prefixes

API keys have distinct scopes and behaviors based on their prefix: There is no separate sov_test_ key type — sov_live_ is the only issued, hash-verified key prefix. The scopes column referenced below exists on the api_keys table but is not currently read or enforced by any handler.

​
Generating & Scoping Tokens

​
Dashboard Generation

  1. Navigate to the API Keys tab in the dashboard.
  2. Click Generate New Key.
  3. Give it a human-readable label (e.g. prod-agent-primary).
  4. Copy the secret immediately — it’s shown once and never recoverable after you close the modal.

​
Blind Authentication Scheme

The client sends the raw API key as a bearer token — it does not hash anything itself. The edge function hashes the received key with sha256(key) and looks it up against the stored key_hash column. This prevents the server from ever storing the raw token value.

​
Header Format

All requests to the sovseal Edge API must supply the bearer token in the standard HTTP headers:

​
Rotation

There is no automatic expiration or scheduled rotation today — keys stay valid until manually revoked. To rotate, generate a new key, redistribute it, verify it works, then revoke the old one.

​
Leaked Key Playbook

If an API key is compromised, follow this immediate mitigation guide:
  1. Immediate Revocation: Visit the API Keys section of the dashboard and select Revoke on the compromised key. The key will be marked as revoked at the edge database immediately (response code 401 api_key_revoked).
  2. Local Key Wiping: Wipe local state. The API token lives in ~/.sovseal/config.json; the encryption master key lives in the OS keychain (0.3.5+). Remove both:
    If you ran with SOVSEAL_KEY_FALLBACK=file, delete the fallback key file under ~/.sovseal/ instead.
  3. Emergency Key Rotation: For teams sharing context via team collaboration:
    • Revoking a member deletes their key grants.
    • Trigger a Data Encryption Key (DEK) rotation from the settings panel.
    • The remaining members’ keys are re-wrapped using a newly generated DEK, rendering the leaked key unable to decrypt history even if they pulled the raw ciphertexts.

​
Per-Key Audit Logs

Every request authenticated by a specific API key is logged in the project audit log. You can monitor request timestamp (UTC), IP address and country (Layer A metadata), operation type (store_memory, recall_memory, check_in), data volume, and latency. Plaintext memory contents are never logged, keeping the audit log entirely zero-knowledge.