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

# Manage API Keys in the sovseal Console

> Generate, scope, rotate, and revoke the tokens your agents use — including token types, blind auth, rotation policies, and a leaked-key playbook.

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.

<Note>
  **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.
</Note>

## Token Types

sovseal issues two distinct token prefixes. Each prefix signals a different trust level and environment scope.

| Prefix      | Name              | Environment                 | Permissions                                                                                         |
| ----------- | ----------------- | --------------------------- | --------------------------------------------------------------------------------------------------- |
| `sov_live_` | Production key    | Live project                | Full project access: replicate, read envelopes, write. Issued via **API Keys** in the console.      |
| `sov_proj_` | Local project key | Local-first / self-asserted | Generated by the MCP plugin on first run. No account required. Used for Hobby-tier local workflows. |

<Note>
  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.
</Note>

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

| Scope             | Allows                                                                      |
| ----------------- | --------------------------------------------------------------------------- |
| `write:snapshots` | Agent write-behind replication — pushing encrypted envelopes to the server. |
| `read:snapshots`  | Agent state synchronization — pulling snapshot updates from the server.     |
| `admin`           | Key rotation, member management, and DEK operations.                        |

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

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

## Generating a Key

<Steps>
  <Step title="Open API Keys settings">
    In the sovseal console, navigate to your project and select the **API Keys** tab from the left sidebar.
  </Step>

  <Step title="Click Generate New Key">
    Press the **Generate New Key** button. A modal opens prompting you to configure the key before it is created.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Set the environment variable">
    Add the key to your agent's runtime environment:

    ```bash theme={null}
    export SOVSEAL_PROJECT_TOKEN="sov_live_4a1b2c3d..."
    ```

    For persistent configuration, write it to `~/.sovseal/config.json` under the `api_key` field.
  </Step>
</Steps>

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

<Warning>
  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.
</Warning>

<Steps>
  <Step title="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.
  </Step>

  <Step title="Wipe local state">
    Remove the exposed token from your local environment:

    ```bash theme={null}
    rm ~/.sovseal/config.json
    # macOS: remove the keychain entry
    security delete-generic-password -s sovseal -a master
    ```

    If you ran with `SOVSEAL_KEY_FALLBACK=file`, delete the fallback key file under `~/.sovseal/` instead.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](/platform/console/teams-and-rbac) for the full revocation protocol.
  </Step>
</Steps>