---
title: "RevDesk API Authentication and Scopes"
description: "Machine-readable RevDesk API-key authentication, least-privilege scope, error, and revocation guide."
canonical: "https://www.revdesk.com/auth.md"
product: "RevDesk"
publisher: "Cell Labs, Inc."
---

# RevDesk API authentication

## Discover

- API base: https://api.revdesk.com/v1
- OpenAPI: https://www.revdesk.com/openapi.json
- Protected-resource metadata: https://api.revdesk.com/.well-known/oauth-protected-resource
- Human-readable guide: https://docs.revdesk.com/api-reference/authentication

## Pick a method

Use an organization-scoped RevDesk API key. RevDesk does not currently advertise automated `agent_auth` registration, a `register_uri`, a `claim_uri`, or identity-assertion exchange. A person remains in control of credential creation and scope selection.

## Register

Create a RevDesk account, create or join an organization, and open Settings > API Keys. Automated dynamic client registration is not supported for v1 API keys.

## Claim

No anonymous credential claim or `identity_assertion` exchange is supported. An authenticated organization member creates the credential and chooses its scopes.

## Obtain a credential

1. A person signs in to RevDesk and opens Settings > API Keys.
2. Create an organization-scoped key and select only the scopes the integration needs.
3. Copy the plaintext key when it is shown. RevDesk stores only its hash and cannot show it again.
4. Store the key in the agent host's secret store, never in a prompt or source file.

## Use the credential

RevDesk v1 accepts the key only as an HTTP Bearer credential:

```http
Authorization: Bearer rv_your_api_key_here
```

## Supported scopes

- `account:read`
- `agents:read`
- `agents:write`
- `bookings:read`
- `brand:read`
- `brand:write`
- `caller_trust:read`
- `caller_trust:write`
- `calls:read`
- `calls:write`
- `contacts:read`
- `contacts:write`
- `jobs:read`
- `jobs:write`
- `phone_numbers:read`
- `phone_numbers:write`
- `sms:read`
- `sms:write`
- `sub_entities:read`
- `sub_entities:write`
- `tokens:mint`
- `transcripts:read`
- `usage:read`
- `voice:read`
- `voice:webrtc`
- `voice:write`
- `webhooks:read`
- `webhooks:write`

## Errors and recovery

- `401 unauthorized`: create, replace, or correctly format the Bearer key. The response includes `WWW-Authenticate` and the protected-resource metadata URL.
- `403 scope_missing`: create or update a key with the single scope named in `error.fields.required_scope`.
- `429 rate_limited`: respect `Retry-After` and the `RateLimit` response fields.

## Revoke

Delete the key in Settings > API Keys. Revocation invalidates the key immediately and also invalidates bounded client tokens derived from it. Use separate keys per environment and agent so each integration can be revoked independently.