Authentication

Every public-API request authenticates with a per-assistant API key. Keys are issued from the web UI, scoped to one assistant, and revocable.

Key format

Plaintext keys look like sk_live_<keyId>_<secret>. The keyId segment is a UUID; the secret is 32 random bytes (base64url). The full key is shown ONCE at creation. We store a scrypt hash plus a 12-character display prefix. There is no recovery path.

Authorization header

Pass the key in a standard Bearer header on every request:

Authorization: Bearer sk_live_a1b2c3d4-...-...-...-............_eXBlOiJKV1QiLCJhb...

Lifecycle

• Create: assistant detail → API tab → New key. Plaintext is shown once.
• List: same tab. Returns name, prefix, last-used timestamp, status. Plaintext is never returned by GET.
• Revoke: row → Revoke. The key returns 403 immediately and forever.
• Rotate: create a new key, deploy the new key to your service, then revoke the old one. There is no transactional "rotate" because overlap is what you want during deploy.