> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovseal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication & Tokens

> API key types, scopes, rotation, and revocation.

## 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:

| Prefix      | Name              | Scopes & Permissions                                    | Tier                                 |
| :---------- | :---------------- | :------------------------------------------------------ | :----------------------------------- |
| `sov_live_` | Production Key    | Full project access (replicate, read envelopes, write). | Paid (Starter/Growth/Pro/Enterprise) |
| `sov_proj_` | Local Project Key | MCP plugin self-asserting. Self-generated on first run. | Hobby (Free)                         |

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:

```http theme={null}
Authorization: Bearer <your-api-key>
```

***

## 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:
   ```bash theme={null}
   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 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.