Authentication

Send your key in the Authorization header on every request. Keys are prefixed vokse_sk_ so they are easy to spot in logs (treat them like passwords and never commit them).

Authorization: Bearer vokse_sk_3f8a…

Open Settings → API keys in the vokse app and create a key. You will see the secret exactly once at creation time, so copy it immediately. Give each integration its own key so you can revoke one without breaking the others.

1. Go to Settings → API keys.
2. Click "Create key", name it after the integration.
3. Select the minimum scopes the integration needs.
4. Copy the secret. It is shown only once.

Every key is minted inside one household and can only act on it. Scoped routes carry the household id in the path, but you rarely need to look it up: the literal segment current always resolves to the household your key belongs to. Fetch the real id once if you want it:

curl -H "Authorization: Bearer vokse_sk_3f8a…" \     https://api.vokse.ai/households/current

Every example in this reference uses current, so it runs as-is with just your key. Prefer explicit ids? Copy yours from Settings → Members in the app, or send it in the X-Household-Id header instead of the path.

Each key carries a set of scopes. A request is only allowed if the key holds the scope the endpoint requires (shown as the scope badge on every endpoint). Scopes come in three classes:

• read:* grants read-only access to a resource (safe, idempotent).
• write:* grants create, update and delete on a resource.
• ai:* allows invoking AI features; these are metered against your monthly allowance.

A key can be given an expiry date at creation. Past it, requests fail with API_KEY_EXPIRED. Rotate keys by creating a new one, deploying it, then revoking the old. There is no forced downtime. Revoked keys stop working immediately.