API authentication and keys

Every request to the Verbeo REST API must include a private API key in the Authorization header. Verbeo issues two key types — only one of them can call this API.

Key types

Type	Prefix	Use in REST API?
Private key	`vbr_`	Yes — required for every endpoint in this reference.
Public key	`vbr_pub_`	No — for the embeddable web widget only. The REST API rejects public keys with `403 FORBIDDEN`.

Public keys exist so the browser-side widget can authenticate without exposing your private credentials. They are not a “read-only” REST key — they cannot call any endpoint documented here. If you need read-only REST access, generate a private key and restrict it via your own gateway / proxy.

Generating an API key

Open your workspace settings

Generate a new key

Click Generate New Key and choose Private key. Public keys are intended for the embeddable web widget and will be rejected by every endpoint in this reference.

Copy and store the key

The key is shown only once at creation time. Copy it immediately and store it in a secrets manager or environment variable. Verbeo does not display the full key again after you leave this page.

Rotate keys regularly and use separate keys for different environments (development, staging, production). Restrict keys to the minimum access level your integration needs.

Passing the key in requests

Include your API key as a Bearer token in the Authorization header of every request:

curl -X GET "https://api.verbeo.ai/v1/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Replace YOUR_API_KEY with your actual key value — including the vbr_ or vbr_pub_ prefix.

Error responses

If your key is missing, invalid, or expired, the API returns a 401 response with the standard error envelope:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header"
  }
}

On assistants, tools, phone numbers and Create phone call, a request with no Authorization: Bearer vbr_… header at all is a 401 whose body carries errorMessage instead of error — see Errors. Check the HTTP status before you read error.code. If you send a public key (vbr_pub_…), the request is recognized but refused with 403:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Public API keys cannot access the REST API. Use a private key (vbr_…)."
  }
}

See Errors for the full envelope and how to handle other error codes.

Security best practices

Never commit API keys to version control or expose them in client-side code.
Store keys in environment variables or a dedicated secrets manager.
Revoke compromised keys immediately from Settings → API Keys in the dashboard.
Use the minimum key privilege required — prefer public keys for read-only integrations.

Overview

Assistants

Tools

Phone Numbers

Calls

Campaigns

Webhooks

API authentication and keys

Key types

Generating an API key

Passing the key in requests

Error responses

Security best practices

​Key types

​Generating an API key

​Passing the key in requests

​Error responses

​Security best practices

Key types

Generating an API key

Passing the key in requests

Error responses

Security best practices