Skip to main content

​
Bearer token

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

​
Getting your API key

Create and manage keys in Settings → API Keys. Each key is prefixed with rv_ and should be kept secret.
API keys are hashed before storage (SHA-256). The plaintext is shown only once, at creation. If you lose it, generate a new one.

​
Key format

​
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. A key created without narrowing gets every scope except compliance:write, which is opt-in only.
agents:read and agents:write govern /v1/agents, which returns assistants: the runtime voices attached to your numbers and campaigns. These are not the same objects as the coworkers you hire in the product, and the counts will not match. There is no coworkers scope.
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