Bearer token
All API requests require a Bearer token in the Authorization header.
curl https://api.revdesk.com/api/v1/voice/calls \
-H "Authorization: Bearer revdesk_your_api_key_here"
Getting your API key
API keys are provisioned when your account is set up. Each key is prefixed with revdesk_ and should be kept secret.
API keys are hashed before storage. If you lose your key, you will need to generate a new one.
| Component | Example |
|---|
| Prefix | revdesk_ |
| Token | a1b2c3d4e5f6... (32 hex characters) |
| Full key | revdesk_a1b2c3d4e5f6... |
Key scopes
Every API key is tied to one of three scopes, which controls what resources the key can see:
| Scope | teamId | Sees |
|---|
| User | null | The user’s personal resources + every team the user is a member of. |
| Organization | umbrella org id | Every resource across the umbrella, including all child sub-entities. Use for HQ engineering or internal tools. |
| Sub-entity | sub-entity id | Only that sub-entity’s resources (phone numbers, calls, contacts, etc.). Caller-trust reads walk up to the parent umbrella’s registration. Use when issuing keys to per-location ops or a vendor managing a single workspace. |
- One key for everything? → organization-scoped.
- Vendor needs to manage one location? → sub-entity-scoped. Revoke the key without affecting the rest of the org.
- Solo developer / single-user account? → user-scoped.
See Sub-entities for how to provision sub-entities and issue per-sub-entity keys.
Security best practices
- Store API keys in environment variables, never in source code
- 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 SHA256 hash)
- Use separate keys for development and production
- Use the smallest scope that works — prefer sub-entity-scoped keys for per-location vendor integrations
- Monitor key usage via the account endpoint