Authentication & Tokens

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:

Generating & Scoping Tokens

Dashboard Generation

1. Navigate to the API Keys tab in the dashboard.
2. Click Generate New Key.
3. Choose the target environment (Production or Sandbox).
4. Select Scopes:
   • write:snapshots: Allow agent writes.
   • read:snapshots: Allow agent state synchronization.
   • admin: Allow key rotation and management (restricted to dashboard auth).

Blind Authentication Scheme

When sending requests, the client hashes the API key before sending it to the edge function. The edge function verifies sha256(project_id || ":" || key). This prevents the server from learning the raw token value.

Header Format

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

Authorization: Bearer <your-api-key>
X-Project-Id: <your-project-id>

Example HTTP Request

POST /functions/v1/v2-agent-state/snapshot HTTP/1.1
Host: ksrlmubaxzwufziwarps.supabase.co
Authorization: Bearer sov_live_4a1b2c3d...
X-Project-Id: proj_8f7e6d...
Content-Type: application/json

{
  "active_context": {
    "ciphertext": "base64-encoded-aes-gcm-data...",
    "iv": "96bit-hex-iv...",
    "tag": "auth-tag..."
  }
}

Rotation & Expiry Policies

API keys can be configured with automatic expiration windows:

• Rolling Rotation: Rotate keys every 30, 90, or 180 days automatically.
• Grace Window: During rotation, the old key remains valid for 24 hours to prevent edge client disconnection before the new key is fully distributed.

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:

   rm ~/.sovseal/config.json
   # macOS: remove the keychain entry (service "sovseal", account "master")
   security delete-generic-password -s sovseal -a master

   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 & Country (Layer A metadata).
• Operation Type (store_memory, recall_memory, check_in).
• Data Volume (bytes transferred).
• Latency (ms).

Plaintext memory contents are never logged, keeping the audit log entirely zero-knowledge.