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

# Authentication

> Authenticate API requests using Bearer tokens.

## Bearer token

All API requests require a Bearer token in the `Authorization` header.

```bash theme={null}
curl https://api.revdesk.com/v1/calls \
  -H "Authorization: Bearer rv_your_api_key_here"
```

## Getting your API key

Create and manage keys in **Settings → API Keys**. Each key is prefixed with `rv_` and should be kept secret.

<Note>
  API keys are hashed before storage (SHA-256). The plaintext is shown only once, at creation. If you lose it, generate a new one.
</Note>

## Key format

| Component | Example              |
| --------- | -------------------- |
| Prefix    | `rv_`                |
| Token     | `a1b2c3d4e5f6...`    |
| Full key  | `rv_a1b2c3d4e5f6...` |

## Scopes

Every key belongs to one organization and carries an explicit list of **scopes** that gate which
endpoints it can call. Each endpoint declares the scope it requires; a request missing that scope is
rejected with `scope_missing`.

| Scope                                        | Grants                                                                                                                           |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `voice:read` / `voice:write`                 | Read / place voice calls and read voice usage.                                                                                   |
| `voice:webrtc`                               | Issue browser WebRTC calling tokens (`POST /v1/webrtc-token`). Narrow by design: a key with only this scope can do nothing else. |
| `phone_numbers:read` / `phone_numbers:write` | List / provision and configure phone numbers.                                                                                    |
| `calls:read` / `calls:write`                 | Read call metadata / place and control calls. `calls:read` covers metadata only.                                                 |
| `recordings:read`                            | Access call **recording audio** (`recording_url`). Sensitive — separate from `calls:read`.                                       |
| `transcripts:read`                           | Access call **transcripts** and analysis (`GET /v1/calls/{id}/transcript`). Sensitive — separate from `calls:read`.              |
| `sms:read` / `sms:write`                     | Read / send SMS.                                                                                                                 |
| `sub_entities:read` / `sub_entities:write`   | List / create and update managed sub-entities.                                                                                   |
| `compliance:write`                           | Change HIPAA mode on a sub-entity. Sensitive — **never granted by default**; request it explicitly.                              |
| `usage:read`                                 | Read usage metrics.                                                                                                              |
| `caller_trust:*` / `brand:*`                 | Caller-ID trust + brand registration.                                                                                            |

Keys are **organization-scoped**: every key reads and writes within a single organization, and tenant
isolation is enforced server-side on every endpoint. Grant the **smallest set of scopes** that the
integration needs (e.g. a browser-calling integration only needs `voice:webrtc`).

## Security best practices

* Store API keys in environment variables, never in source code
* Grant the smallest scope set that works (e.g. `voice:webrtc` only for browser calling)
* Rotate keys periodically: revoke the old key in Settings → API Keys, then issue a new one (plaintext is shown once at creation; we only store the SHA-256 hash)
* Use separate keys for development and production
* Monitor key usage via the account endpoint