> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verbeo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API authentication and keys

> Learn about Verbeo's two API key types, which endpoints each one can access, how to generate keys from the dashboard, and how to pass them in requests.

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

<Note>
  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.
</Note>

## Generating an API key

<Steps>
  <Step title="Open your workspace settings">
    Log in to the Verbeo dashboard and navigate to **Settings → API Keys**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

## Passing the key in requests

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

```bash theme={null}
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:

```json theme={null}
{
  "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](/api-reference/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`:

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

See [Errors](/api-reference/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.