> For the complete documentation index, see [llms.txt](https://docs.voiceb.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voiceb.ai/credentials.md).
# Credentials
Let your agent call APIs that sit behind a login — OAuth2 client-credentials, custom token endpoints, expiring bearer tokens — without ever putting a secret in a tool or showing it to the model.
***
## Credentials
Most enterprise APIs are not protected by a fixed API key. They issue a short-lived access token from a token endpoint, and every request has to carry a valid one. A Tool on its own can only send static headers, so until now an API with an expiring token was out of reach for the agent.
**Credentials** solves this. You describe once, per campaign, how to obtain a token: where to request it, what to send, and how to read it out of the response. VoiceB stores that configuration encrypted, obtains and refreshes the token on its own, and attaches it to the agent's tool calls server-side. The agent, and the model behind it, never see the credential.
Credentials are used in two places:
* **Tools** — any tool with **Use auth proxy** enabled calls the customer's API through VoiceB's proxy, which injects the token.
* **Webhook integrations** — the post-call webhook can authenticate with a stored credential instead of a fixed token.
### How it works
1. You create a credential in the campaign, with a **key** (e.g. `acme_crm`) and the instructions to obtain a token.
2. In a tool, you enable **Use auth proxy** and reference the credential by key. The tool is published to the voice provider pointing at VoiceB's proxy instead of the customer's API.
3. During the call, the agent invokes the tool exactly as before, sending only the tool's normal parameters.
4. VoiceB resolves the credential for that campaign (reusing a cached token, or requesting a new one if it is about to expire), builds the real request to the customer's API, attaches the token, and returns the response to the agent.
The upstream URL, method and headers are read server-side from the stored tool definition — never from the agent's payload. A prompt-injected agent cannot redirect your credentials to a different URL, and the schema the model sees is identical whether the auth proxy is on or off.
### Setting it up
Credentials are configured per campaign:
1. Open the campaign and go to **Credentials** in the left sidebar.
2. Click **Add Credential**.
3. Fill in the fields below and click **Add Credential**.
#### Identity
| Field | What to enter |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Label** | A readable name shown in the list (e.g. `Acme CRM — production`). |
| **Key** | The identifier tools and webhooks use to reference this credential (e.g. `acme_crm`). One tool definition can be reused across campaigns: each campaign resolves the same key to its own credential. |
| **Auth type** | How the token is obtained. **Custom token request** lets you describe any token endpoint (OAuth2 client-credentials, a login POST that returns a JWT, etc.). |
#### Token request
This is the request VoiceB sends to obtain a token.
| Field | What to enter |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Token URL** | The endpoint that issues the token (e.g. `https://api.example.com/oauth/token`). |
| **HTTP method** | Usually `POST`. |
| **Body encoding** | `Form (application/x-www-form-urlencoded)` for standard OAuth2 endpoints; `JSON` for login endpoints that expect a JSON body. |
| **Request headers** | Any header the token endpoint requires (e.g. `Accept: application/json`, or a `Basic` header for client authentication). |
| **Request body** | The fields of the token request (e.g. `grant_type = client_credentials`, `scope = read`). Reference a secret with `{{secret_name}}`. |
| **Secrets** | The sensitive values of the request — `client_id`, `client_secret`, `password`, API keys. Secrets are stored encrypted and are never displayed again after saving. |
{% hint style="info" %}
Put sensitive values in **Secrets** and reference them from headers or body fields, rather than typing them directly into a field. Only secrets are encrypted at rest and masked in the UI.
{% endhint %}
#### Reading the token
VoiceB needs to know where the token is in the response, and for how long it is valid.
| Field | What to enter |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Token path** | Path to the token inside the JSON response, in dot notation. `access_token` for standard OAuth2; `data.token` if the token is nested. |
| **Expires-in path** | Path to the token lifetime in the response, in seconds (`expires_in` for OAuth2). |
| **Fixed TTL (seconds)** | Used when the response does not include an expiry, or the expires-in path does not resolve. At least one of **Expires-in path** or **Fixed TTL** is required. |
| **Refresh skew (seconds)** | How long before expiry VoiceB requests a fresh token. Default `60`. Raise it for APIs with clock drift or slow token endpoints. |
#### Attaching the token
How the token is added to the agent's requests once obtained.
| Field | What to enter |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Attach token as** | `Header` (default) or query parameter. |
| **Attach token name** | The header or parameter name. `Authorization` for bearer tokens. |
| **Attach token prefix** | Text placed before the token value. `Bearer` produces `Authorization: Bearer `. Leave empty for APIs that expect the raw token. |
#### Example — OAuth2 client credentials
| Field | Value |
| --------------- | ----------------------------------------------------------------------------------------------------------- |
| Token URL | `https://api.acme.com/oauth/token` |
| HTTP method | `POST` |
| Body encoding | Form |
| Request body | `grant_type` = `client_credentials` · `client_id` = `{{client_id}}` · `client_secret` = `{{client_secret}}` |
| Secrets | `client_id`, `client_secret` |
| Token path | `access_token` |
| Expires-in path | `expires_in` |
| Attach token as | Header · `Authorization` · `Bearer` |
### Using a credential in a tool
1. Open **Tools** and edit (or create) the tool that calls the protected API.
2. Enable **Use auth proxy**.
3. Select the credential by **key**.
4. Keep the tool's URL, method, parameters and description as they are — they describe the customer's API, not the proxy. VoiceB rewrites the published endpoint automatically.
5. Run a **test call** before attaching the tool to a production agent.
If the API returns large responses, configure the tool's **response filter** to keep only the fields the agent needs. The proxy applies the filter before the response reaches the model, so a multi-megabyte payload becomes a few relevant fields.
Tools — Connect your agent to external actions → · Tool execution modes →
### Using a credential in a webhook integration
1. Open **Integrations** and select the webhook integration.
2. In the authentication setting, choose between **Fixed token** (the current behaviour — a static token sent on every request) and **Stored credential**.
3. Pick the credential by key.
The webhook now logs in the same way a tool does: VoiceB obtains and refreshes the token, and no secret is shown in the integration settings.
### Good to know
* **Scope.** Credentials belong to a campaign. A tool shared across campaigns resolves the credential as *campaign + key*, so the same tool can hit the same API with different credentials in each campaign. Credentials are never visible across organizations.
* **Caching.** Tokens are cached and reused across calls until they are within the refresh skew of expiring. A busy campaign does not hit your token endpoint once per call.
* **No change for the agent.** Enabling the auth proxy does not change the tool's schema or description. Scripts and prompts that already use the tool keep working.
* **Secrets are write-only.** Once saved, a secret cannot be read back from the UI or from Agent Studio. To rotate a secret, edit the credential and enter the new value.
* **What the model sees.** Only the tool's normal parameters leave the agent. Upstream URL, headers, secrets and tokens live server-side in VoiceB and are injected by the proxy.
### Troubleshooting
| Symptom | Likely cause |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tool fails with `401` / `403` through the proxy | Token path or attach settings don't match what the API expects. Check the API's documented auth header and prefix. |
| Token request fails | Wrong body encoding (Form vs JSON), a missing header, or a secret referenced with the wrong name. Test the token request with the same fields outside VoiceB first. |
| Token works once, then fails | No valid expiry: the expires-in path doesn't resolve and no Fixed TTL is set, or the TTL is longer than the real token lifetime. Set a Fixed TTL below the API's token lifetime. |
| Save button stays disabled | A required field is empty — Label, Key, Token URL, and at least one of Expires-in path or Fixed TTL. |
Data Journey, Storage & Security →
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.voiceb.ai/credentials.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
