> ## 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 sovseal API Keys via REST Endpoints

> Issue new sov_live_ API keys, list active and revoked keys, and immediately revoke keys — all from the authenticated account management surface.

<style>
  {`
      main, article, .prose {
        margin-left: 2.5cm !important;
        margin-right: 2.5cm !important;
      }
      `}
</style>

The API Keys endpoints let you issue, inspect, and revoke programmatic `sov_live_` keys that you assign to your production agents. These endpoints operate at the account level — they manage the keys themselves, not the agent data those keys protect. Because the server never stores raw key material, the full secret for any new key is returned exactly once at creation time; you are responsible for storing it securely.

<Warning>
  **Session JWT required.** All API key management endpoints require your WorkOS AuthKit session JWT. Sending a `sov_live_` or `sov_proj_` token returns `401 session_jwt_required`. Use the WorkOS session your dashboard login provides.
</Warning>

***

## POST /api-keys

Generate a new `sov_live_` API key. The key is stored server-side as a SHA-256 hash only — the plaintext `raw_secret` is returned once and never accessible again.

```http theme={null}
POST /api-keys
Authorization: Bearer <SESSION_JWT>
Content-Type: application/json
```

<ParamField body="name" type="string" required>
  A human-readable label for this key (e.g. `"my-trading-agent"`). Between 1 and 128 characters. Used for identification in the dashboard and in list responses.
</ParamField>

### Response — 201 Created

<ResponseField name="id" type="string">
  UUID of the new API key record. Use this as the `:id` path parameter to revoke the key later.
</ResponseField>

<ResponseField name="name" type="string">
  The label you supplied in the request body.
</ResponseField>

<ResponseField name="prefix" type="string">
  Always `"sov_live_"`.
</ResponseField>

<ResponseField name="masked_key" type="string">
  Partially masked version of the key for display in UIs and logs.
</ResponseField>

<ResponseField name="raw_secret" type="string">
  The full `sov_live_` key secret. **This is the only time you will receive it.** Store it immediately in a secret manager or environment variable.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO-8601 timestamp of when the key was created.
</ResponseField>

```json theme={null}
{
  "id": "1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  "name": "my-trading-agent",
  "prefix": "sov_live_",
  "masked_key": "sov_live_8f3a****************b2a1",
  "raw_secret": "sov_live_8f3a2b1c4d9e0f...b2a1",
  "created_at": "2026-06-09T16:45:30.123Z"
}
```

### curl Example

```bash theme={null}
curl -X POST https://ksrlmubaxzwufziwarps.supabase.co/functions/v1/v2-agent-state/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-trading-agent"}'
```

***

## GET /api-keys

Retrieve a list of all API keys — active and revoked — associated with the authenticated account. Keys are returned in masked form; the raw secret is never re-exposed.

```http theme={null}
GET /api-keys
Authorization: Bearer <SESSION_JWT>
```

### Response — 200 OK

Returns a JSON array of key records:

<ResponseField name="[].id" type="string">
  UUID of the API key record.
</ResponseField>

<ResponseField name="[].name" type="string">
  Human-readable label for the key.
</ResponseField>

<ResponseField name="[].prefix" type="string">
  Always `"sov_live_"`.
</ResponseField>

<ResponseField name="[].created_at" type="string">
  ISO-8601 timestamp of when the key was issued.
</ResponseField>

<ResponseField name="[].revoked_at" type="string | null">
  ISO-8601 timestamp of when the key was revoked, or `null` if still active.
</ResponseField>

<ResponseField name="[].last_used_at" type="string | null">
  ISO-8601 timestamp of the most recent authenticated request using this key.
</ResponseField>

<ResponseField name="[].status" type="string">
  Current state of the key. Either `"active"` or `"revoked"`.
</ResponseField>

```json theme={null}
[
  {
    "id": "1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
    "name": "my-trading-agent",
    "prefix": "sov_live_",
    "created_at": "2026-06-09T16:45:30.123Z",
    "revoked_at": null,
    "last_used_at": "2026-06-09T16:50:00.000Z",
    "status": "active"
  }
]
```

### curl Example

```bash theme={null}
curl -G https://ksrlmubaxzwufziwarps.supabase.co/functions/v1/v2-agent-state/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_JWT"
```

***

## DELETE /api-keys/:id

Revoke an API key immediately. Revocation is permanent and cannot be undone. Any agent still using the key will receive `401 api_key_revoked` on all subsequent requests.

```http theme={null}
DELETE /api-keys/:id
Authorization: Bearer <SESSION_JWT>
```

**Path Parameters:**

| Parameter | Type   | Description                                                                          |
| --------- | ------ | ------------------------------------------------------------------------------------ |
| `id`      | string | UUID of the API key to revoke. Obtain this from `POST /api-keys` or `GET /api-keys`. |

### Response — 200 OK

<ResponseField name="id" type="string">
  UUID of the revoked key.
</ResponseField>

<ResponseField name="revoked_at" type="string">
  ISO-8601 timestamp of when the revocation was processed.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation string. Always `"api_key_revoked"` on success.
</ResponseField>

```json theme={null}
{
  "id": "1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  "revoked_at": "2026-06-09T16:55:00.000Z",
  "message": "api_key_revoked"
}
```

### curl Example

```bash theme={null}
curl -X DELETE https://ksrlmubaxzwufziwarps.supabase.co/functions/v1/v2-agent-state/api-keys/1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6 \
  -H "Authorization: Bearer YOUR_SESSION_JWT"
```