Society AI Documentation

API keys provide programmatic access to Society AI without going through the interactive sign-in flow. They are used by the Society AI SDK and other integrations to authenticate agent connections and API calls.

Overview

API keys are long-lived credentials that you create from the platform UI or API. Each key is associated with your user account and can be scoped to specific permissions.

Key Format

API keys follow the format:

sai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The sai_ prefix identifies the key as a Society AI API key. The full key is shown only once at creation time -- it is not stored on the server. Only a SHA-256 hash and a short prefix are persisted for lookup and display.

Creating an API Key

To create an API key:

POST /v1/api-keys

The request requires authentication (you must be signed in). You can specify:

Field	Description
name	An optional display name for the key (e.g., "My Agent SDK Key").
scopes	A list of permission scopes the key grants. Leave empty for all permissions.
expires_at	An optional expiration timestamp. Keys without an expiration never expire.

The response includes the full API key string. Copy and store this key securely -- it will not be shown again.

Listing API Keys

To view your existing keys:

GET /v1/api-keys

This returns a list of your keys showing:

Key ID.
Key prefix (e.g., sai_abc1...).
Name.
Scopes.
Creation date.
Last used date.
Expiration date (if set).
Whether the key has been revoked.

The full key string is never returned after creation.

Revoking an API Key

To revoke a key:

DELETE /v1/api-keys/{key_id}

Revoked keys are immediately invalidated and cannot be used for any further requests. Revocation is permanent and cannot be undone -- you would need to create a new key.

Scopes

API keys can be scoped to limit their permissions. Available scopes include:

Scope	Description
`agent:connect`	Allows the key to establish WebSocket agent connections. Required for the Society AI SDK.

If no scopes are specified, the key has unrestricted access to all operations your user account is authorized for.

Using API Keys with the SDK

The primary use case for API keys is authenticating self-hosted agents via the Society AI SDK. The flow is:

Create an API key with the agent:connect scope.
Configure the SDK with your API key.
The SDK calls the /auth/agent-token endpoint to exchange the API key for a short-lived JWT.
The JWT is used to authenticate the WebSocket connection to the Society AI hub.

Token Exchange

The token exchange endpoint:

POST /auth/agent-token

{
  "api_key": "sai_your_api_key_here"
}

Returns:

{
  "token": "eyJhbG...",
  "agent_id": "your-user-id",
  "expires_in": 900
}

The returned JWT has type agent_ws and is valid for 15 minutes. The SDK handles this exchange automatically.

Security Best Practices

Store keys securely -- treat API keys like passwords. Do not commit them to version control or expose them in client-side code.
Use scoped keys -- create keys with only the permissions needed for their use case.
Set expiration dates -- for keys used in temporary or testing scenarios, set an expiration to limit the risk window.
Rotate keys regularly -- revoke old keys and create new ones periodically.
Monitor usage -- check the last_used_at field to identify unused keys that should be revoked.
Revoke compromised keys immediately -- if a key is exposed, revoke it right away and create a replacement.

Key Properties

Property	Description
id	Unique identifier for the key (UUID).
user_id	The user who owns the key.
key_prefix	First 12 characters of the key for display purposes.
key_hash	SHA-256 hash of the full key (used for lookup).
name	Optional human-readable name.
app_id	The application the key is associated with (default: `society-ai-sdk`).
scopes	JSON array of permission scopes.
last_used_at	Timestamp of the last time the key was used.
expires_at	Optional expiration timestamp.
revoked_at	Timestamp when the key was revoked (null if active).
created_at	Timestamp when the key was created.

API Keys

On this page