Skip to main content

​
Bearer token

All API requests require a Bearer token in the Authorization header. Registered OAuth clients use short-lived access tokens; other integrations may use organization-scoped RevDesk API keys.

​
Getting your API key

Create a RevDesk account, then create and manage keys in Settings → API Keys. Key creation is self-serve and does not require a sales conversation. Each key is prefixed with rv_ and should be kept secret.

​
OAuth authorization code

OAuth-capable clients discover RevDesk’s authorization server from the API or MCP protected-resource metadata. RevDesk supports authorization code with PKCE (S256) and refresh tokens. During consent, a person selects an organization and approves named v1 scopes. Every API request re-checks that the person is unlocked, the registered client still exists, and the person still belongs to that organization.
Start with a free trial and a separate development organization. RevDesk reaches real carrier networks rather than a simulated public sandbox, so use read-only scopes first and restrict calling or messaging credentials to approved test numbers.
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 tasks. These are not the same objects as the agents you hire in the product, and the counts will not match. There is no agents 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).
Lead intake endpoints do not use API keys. Each lead source has a rotatable URL token and source secret so a CRM or form provider can deliver leads without receiving access to the rest of your workspace. See Tasks and lead sources. The retired /v1/workflows, /v1/workflows/{id}/enroll, and /v1/workflow_contacts endpoints and their workflow-only scope are no longer available; use /v1/tasks for programmatic work. /v1/jobs remains a deprecated compatibility alias.

​
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