Skip to main content
API keys are the credential layer between your agents and the sovseal replication server. Every SDK call and MCP client request must carry a bearer token that the server validates before accepting an envelope write or returning a snapshot pull. Under sovseal’s blind authentication scheme, the server never stores your raw token value — only a SHA-256 hash — so even a full database leak cannot expose a usable key. This page covers token types, how to generate keys, and the exact steps to follow if a key is compromised.
Provenance Layer: Server-Known (Layer A) — The server tracks key metadata: label, creation date, prefix, last-used timestamp, and the SHA-256 hash of the secret. The raw API key string is shown exactly once at creation time and is never stored or recoverable after you close the modal.

​
Token Types

sovseal issues two distinct token prefixes. Each prefix signals a different trust level and environment scope.
There is no separate sov_test_ key type today — sov_live_ is the only issued, hash-verified key prefix. For isolated testing, use a sov_proj_ token (free, self-asserted, no server-side account) or a second project.

​
Scopes

The api_keys table carries a scopes column (defaulting to {read,write}), but no current handler reads or enforces it — a sov_live_ key today authorizes the full range of project operations regardless of any scope you might assign in a future UI. Treat the scopes concept below as a documented direction, not an enforced restriction yet.

​
Blind Authentication Scheme

sovseal uses a two-step blind authentication protocol so the raw token value is never transmitted to or stored by the server.
  1. Client side — the SDK sends the raw key as a bearer token; it never computes or transmits a hash itself.
  2. Server side — the edge function hashes the received key with sha256(api_key) and looks it up against the stored key_hash column. If they match, the request proceeds. The server never stores the original secret — only this one-way hash.
This means a compromise of the server’s key_hash table yields no usable credentials.

​
Request Header Format

​
Generating a Key

1

Open API Keys settings

In the sovseal console, navigate to your project and select the API Keys tab from the left sidebar.
2

Click Generate New Key

Press the Generate New Key button. A modal opens prompting you to configure the key before it is created.
3

Label the key

Give the key a human-readable label — for example, prod-agent-primary or ci-pipeline-staging — so you can identify it later in the key list and any activity log.
4

Copy the secret immediately

The console displays the full sov_live_... string once in a modal overlay. This value is held only in volatile React component state. Copy it now — clicking away or closing the modal permanently purges it from memory. The server stores only the SHA-256 hash; there is no way to recover the raw key after this step.
5

Set the environment variable

Add the key to your agent’s runtime environment:
For persistent configuration, write it to ~/.sovseal/config.json under the api_key field.

​
Rotation

There is no automatic expiration or scheduled rotation today — keys stay valid until you manually revoke them. To rotate a key, generate a new one, update it in your agent’s environment, verify the new key works, then revoke the old one from the API Keys list.

​
Viewing Key Activity

Each key row in the API Keys table shows the last used timestamp and the originating IP country from the most recent authenticated request. For deeper inspection, the per-key audit log records:
  • Request timestamp (UTC)
  • IP address and country
  • Operation type (store_memory, recall_memory, check_in)
  • Data volume (bytes transferred)
  • Latency (ms)
Plaintext memory contents are never written to the audit log.

​
Leaked Key Playbook

If an API key is accidentally committed to a public repository, exposed in a log file, or otherwise compromised, follow this playbook immediately. The window between exposure and revocation is the only period during which an attacker can make authenticated writes to your project.
1

Revoke the compromised key

Open the API Keys tab in the console. Find the key by its label or prefix and click the Revoke (trash) icon. Revocation issues an immediate database instruction setting revoked_at. The key propagates as invalid through edge cache invalidation in under 5 seconds and responds with 401 api_key_revoked globally.
2

Wipe local state

Remove the exposed token from your local environment:
If you ran with SOVSEAL_KEY_FALLBACK=file, delete the fallback key file under ~/.sovseal/ instead.
3

Generate a replacement key

Follow the key generation steps above to create a fresh sov_live_ key with the same scopes as the revoked key. Update the SOVSEAL_PROJECT_TOKEN environment variable in every agent process and CI/CD secret store.
4

Audit key activity

In the API Keys list, check the revoked key’s last-used timestamp and originating IP country against the estimated exposure window to gauge whether it was used before you caught it.
5

Rotate the DEK if the team key was exposed

If the compromised key had admin scope or was a team-level sub-key, trigger a Data Encryption Key (DEK) rotation from Settings → Security. This generates a fresh DEK, re-wraps it for all remaining active members, and renders the leaked key unable to decrypt any memories written after the rotation epoch — even if the attacker captured raw ciphertexts. See Teams & RBAC for the full revocation protocol.