Authentication

The API uses secret API keys sent as a Bearer token. Agents in the browser use short-lived tokens that your server mints. Webhooks are signed with a separate secret.

API keys

Send your key in the Authorization header on every request, over HTTPS. Live keys start with ll_live_ and test keys with ll_test_. Test keys run every request and every check and place no calls. See test mode.

curl "https://api.liveleg.dev/v1/dial_sessions?limit=10" \
  -H "Authorization: Bearer $LIVELEG_API_KEY"

const res = await fetch('https://api.liveleg.dev/v1/dial_sessions?limit=10', {
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
  },
});
const sessions = await res.json();

import os, requests

sessions = requests.get(
    "https://api.liveleg.dev/v1/dial_sessions",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
    params={"limit": 10},
).json()

Keep keys on your server. Never put one in a browser, a mobile app or a repository. A request with a missing or revoked key returns 401.

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is not valid or has been revoked."
  }
}

Create and scope keys

Create one key for each service that calls the API. Revoking a key affects only that key. Scopes limit what a key can do. A key for your CRM sync might only read call records and recordings. The secret is shown once, when the key is created.

POST/v1/api_keys

curl https://api.liveleg.dev/v1/api_keys \
  -H "Authorization: Bearer $LIVELEG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "crm-sync",
    "mode": "live",
    "scopes": ["call_records:read", "recordings:read"]
  }'

{
  "id": "key_4Fh71",
  "name": "crm-sync",
  "mode": "live",
  "scopes": ["call_records:read", "recordings:read"],
  "secret": "ll_live_8fK2pQ0wZr5mXv1NcT6yHs3a",
  "created_at": "2026-11-03T13:40:11Z"
}

Rotate and revoke

Rolling a key issues a new secret and keeps the old one working for the number of hours you set, up to 7 days. Revoke a key with DELETE /v1/api_keys/{id}. It stops working right away. Every key shows when it was last used.

curl https://api.liveleg.dev/v1/api_keys/key_4Fh71/roll \
  -H "Authorization: Bearer $LIVELEG_API_KEY" \
  -d expire_old_in_hours=24

Agent tokens

The browser SDK connects with a token for one agent, minted by your server with POST /v1/agents/{id}/tokens. A token lasts up to 1 hour and can only carry that agent's audio and call controls. See Agent calling.

Subaccount keys

Keys created in a subaccount only work in that subaccount. Your parent key can act on a subaccount with the Liveleg-Account header. See Subaccounts.

Webhook secrets

Each webhook endpoint has its own signing secret, starting with whsec_. It is used only to check signatures on deliveries and cannot call the API. See Verify signatures.