API Keys

Honesty Ledger (Provenance Layer): API keys are authorized at the Server-known (Layer A) layer.

ZK Trust Boundary:

• What the server sees: Key metadata (labels, creation date, prefix, last used time) and the SHA-256 hash of the secret.
• What stays on device: The raw API key string (visible once upon creation).

---

API Key Management

API keys authenticate your SDK and MCP clients, granting them access to the project's replication queues.

Key Prefixes and Scopes

• sov_live_*: Production API keys issued to paid accounts. These keys authorize write-behind replication and envelope pulls against the database.
• sov_proj_*: Local-first tokens used by self-asserting MCP clients (no account signup required).

Security Architecture

1. "Shown Once" Overlay: When a key is generated, the raw secret string is returned once in a modal overlay. This value is held strictly in volatile React component state and is permanently purged from memory upon closing the dialog.
2. Hashed at Rest: The replication server does not store your API keys. It stores only a cryptographically secure SHA-256 hash of the secret (key_hash). When authenticating requests, the server hashes the incoming bearer token and compares it against the database hash.
3. Sub-5 Second Revocation: Deleting an active key issues an immediate database instruction, setting revoked_at. Revocations propagate globally through edge cache invalidation, taking effect server-side in less than 5 seconds.

Leaked Key Revocation Playbook

If an API key is accidentally committed to public repositories or leaked:

1. Open the API Keys settings tab.
2. Locate the compromised key prefix and click Revoke (trash icon).
3. Generate a new key and update your agent environment (SOVSEAL_PROJECT_TOKEN).
4. Re-verify the sync log to confirm no unauthorized writes occurred during the invalidation window.

---

Offline Reference Analogs: This documentation was written with visual and rhythm reference to platform/agent-signup.html.