> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vocalistic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, client tokens and scopes.

## API keys

Send your key as a bearer token:

```bash theme={null}
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.

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.