Authentication

API keys, client tokens and scopes.

API keys

Send your key as a bearer token:

curl https://api.vocalistic.ai/v1/whoami \
  -H 'Authorization: Bearer YOUR_API_KEY'

A key belongs to your organization, not to the person who created it, so it keeps working if that person leaves. Revoke it when you no longer need it.

Keep keys on your server. For browsers and mobile apps, use a client token.

Creating, editing and rotating keys requires a login session, so a leaked key can’t create more keys. A key with the right scopes can list and revoke keys.

Client tokens

A client token is a short-lived credential that’s safe to give to a browser or mobile app. Your server creates one with POST /v1/client-tokens, and it lasts up to one hour, or 15 minutes by default.

A token’s scopes can’t exceed those of the key that created it. A token keeps working until it expires, even if that key is revoked, so keep lifetimes short.

Scopes

Each key has a list of scopes. A request without the scope it needs returns 403, with the code missing_scope.

Scope	Allows
organization:read, organization:write	View or update your organization
members:read, members:write	View or manage members and invitations
keys:read, keys:write	View or revoke API keys
billing:read, billing:write	Reserved for billing
usage:read, logs:read	Reserved for usage and logs
agents:read, agents:write	Reserved for agents
datasets:read, datasets:write	Reserved for datasets
inference	Reserved for speech and agent calls

You can’t give a key a scope that your own role doesn’t include. GET /v1/roles lists what each role can do.