Manage sovseal API Keys via REST Endpoints

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.

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.

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.

POST /api-keys
Authorization: Bearer <SESSION_JWT>
Content-Type: application/json

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.

Response — 201 Created

string

UUID of the new API key record. Use this as the :id path parameter to revoke the key later.

string

The label you supplied in the request body.

string

Always "sov_live_".

string

Partially masked version of the key for display in UIs and logs.

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.

string

ISO-8601 timestamp of when the key was created.

{
  "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

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.

GET /api-keys
Authorization: Bearer <SESSION_JWT>

Response — 200 OK

Returns a JSON array of key records:

string

UUID of the API key record.

string

Human-readable label for the key.

string

Always "sov_live_".

string

ISO-8601 timestamp of when the key was issued.

string | null

ISO-8601 timestamp of when the key was revoked, or null if still active.

string | null

ISO-8601 timestamp of the most recent authenticated request using this key.

string

Current state of the key. Either "active" or "revoked".

[
  {
    "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

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.

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

string

UUID of the revoked key.

string

ISO-8601 timestamp of when the revocation was processed.

string

Confirmation string. Always "api_key_revoked" on success.

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

curl Example

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"

Get Started

Platform

Agent Plugins

Self-Hosted

Integrations

Cookbooks

API Reference

Release Notes

Manage sovseal API Keys via REST Endpoints

POST /api-keys

Response — 201 Created

curl Example

GET /api-keys

Response — 200 OK

curl Example

DELETE /api-keys/:id

Response — 200 OK

curl Example

​POST /api-keys

​Response — 201 Created

​curl Example

​GET /api-keys

​Response — 200 OK

​curl Example

​DELETE /api-keys/:id

​Response — 200 OK

​curl Example

POST /api-keys

Response — 201 Created

curl Example

GET /api-keys

Response — 200 OK

curl Example

DELETE /api-keys/:id

Response — 200 OK

curl Example