Authentication

Every request to a public Cloove API is authenticated with an API key passed as a bearer token:


Authorization: Bearer clv_live_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

You create and manage keys in the Developer portal under Developer → API keys, or programmatically via the Developer Portal API.

A key’s secret is shown only once, at creation (and on an explicit, password-protected reveal). Store it in a secrets manager - never commit it to source control or ship it in a browser or mobile client.

Key format

API key prefixes identify their environment and credential type:


clv_<environment>_<type>_<random>

Segment	Values	Meaning
`clv`	-	Identifies a Cloove key.
`<environment>`	`test` · `live`	The environment the key operates in.
`<type>`	`sk` · `pk`	Secret key (server-side) or public identifier.
`<random>`	32 chars (secret)	Opaque random string.

Example (test secret key):


clv_test_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Authenticate with the secret key (sk). The environment is inferred from the prefix - a clv_test_… key only ever touches test data, and a clv_live_… key only touches production.

Scopes

Each key is granted a set of scopes that gate exactly what it can do. A request to an endpoint whose scope the key doesn’t hold returns 403 missing_scope.

Scopes are namespaced as resource:action (or resource:subresource:action). As a convenience, a namespace’s parent :read scope grants every child read scope in that namespace - for example, vox:read grants vox:calls:read, vox:numbers:read, and vox:agents:read. A parent read scope never grants a write or create scope.

Scope	Grants
`vox:read`	All Vox read access (calls, numbers, agents)
`vox:calls:read`	Read voice calls
`vox:calls:create`	Place outbound calls
`vox:client_tokens:create`	Issue short-lived web or mobile softphone credentials
`vox:agents:read`	Read AI agents
`vox:numbers:read`	Read voice numbers
`messaging:read`	All messaging read access
`messaging:conversations:read`	Read WhatsApp conversations
`messaging:messages:read`	Read messages
`messaging:messages:send`	Send text and template messages
`contacts:read`	Read contacts/customers
`contacts:write`	Create and update contacts
`products:read`	Read products
`products:write`	Create and update products
`orders:read`	Read orders/sales
`orders:write`	Record orders/sales
`wallet:read`	Read wallet balance and deposit (funding) accounts
`payouts:read`	Read payout (bank) accounts
`payouts:write`	Manage payout accounts
`wallet:withdrawals:read`	Read withdrawals
`wallet:withdrawals:create`	Initiate withdrawals
`finance:read`	All finance read access (summaries, transactions)
`finance:summary:read`	Read financial summaries
`finance:transactions:read`	Read the transaction ledger, requery status, generate receipts
`payment_links:read`	Read payment links
`payment_links:write`	Create and cancel payment links
`hotel:read`	All hotel read access (rooms and reservations)
`hotel:rooms:read`	Read room types and rooms
`hotel:rooms:write`	Create room types and rooms
`hotel:reservations:read`	Read availability and reservations
`hotel:reservations:write`	Create, check in, check out, and cancel reservations
`webhooks:read`	Read webhook configuration
`webhooks:write`	Manage webhook endpoints

Grant a key the least privilege it needs. A backend that only places AI calls needs vox:calls:create (and perhaps vox:calls:read). A backend serving browser softphone credentials needs vox:client_tokens:create; the browser must never receive that API key.

Access controls

Developer API access requires either an active trial or an active subscription whose effective benefits include API Access. Effective benefits include approved subscription overrides, business feature flags, and active add-ons. When access is unavailable, existing keys return 403 api_access_not_included and outbound webhook deliveries are paused.

Beyond subscription entitlement and scopes, a key can be locked down further when you create or update it:

Allowed IP ranges - restrict use to specific IPs or CIDR ranges. Requests from other addresses get 403 ip_not_allowed.
Allowed origins - restrict by Origin/Referer host. Other origins get 403 origin_not_allowed.
Expiry - set an expires_at; the key stops working after that time (401 expired_api_key).

Finance write scopes require an IP allowlist on live keys. Any live key granted payouts:write or wallet:withdrawals:create must define at least one allowed IP range - key creation is rejected otherwise. Initiating withdrawals additionally requires a per-key withdrawal policy. See Wallet & payouts.

Developer portal authentication

The endpoints under /api/developer that manage keys, apps, and webhook endpoints are not authenticated with an API key. They use your dashboard session (a JWT bearer token) plus the MANAGE_DEVELOPER_KEYS permission and an active business context. This keeps key management gated behind a real, logged-in operator. See the Developer Portal API.