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

Keys are structured strings so you can recognize them at a glance:


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: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
`payouts:read`	Read payout (bank) accounts
`payouts:write`	Manage payout accounts
`wallet:withdrawals:read`	Read withdrawals
`wallet:withdrawals:create`	Initiate withdrawals
`webhooks:read`	Read webhook configuration
`webhooks:write`	Manage webhook endpoints

Grant a key the least privilege it needs. A backend that only places calls needs vox:calls:create (and perhaps vox:calls:read), nothing more.

Access controls

Beyond 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.