---
title: "API connections"
description: "Save an API base URL, authentication, and headers once, then reuse them in Custom API actions and widget functions for the same agent."
---

An **API connection** saves a base URL and the credentials and headers sent with requests to that API. Use it in one or more [Custom API actions](/docs/actions/custom-api) and widget [Call API functions](/docs/widgets/functions-and-states#call-api).

Connections belong to one agent. They are not shared with other agents or teams.

## Create a connection

In your agent, go to **Build** > **API connections** and select **Create connection**. Enter a name and the API's base URL, then set authentication or add headers if the API requires them.

The base URL must use HTTPS and point to a public address. You can include a path such as `https://api.example.com/v1`, but not a query, fragment, or variable. Add the endpoint path in the action or widget function that uses the connection.

## Authentication

Choose the method your API expects:

| Type | What Chatvox sends |
| --- | --- |
| **None** | No authentication. |
| **Bearer token** | An `Authorization: Bearer` header. |
| **Basic auth** | A username and password. |
| **API key header** | An API key in a header with the name you choose. |
| **API key query param** | An API key in a query parameter with the name you choose. |

Use **Headers** to add other HTTP headers that every request needs. Chatvox encrypts saved secrets and masks them in the editor. Select **Replace** to enter a new secret. Saving without replacing it keeps the saved value.

## Test the connection

In the connection's **Test** card, choose a method and enter a **Path and query**, such as `/orders?limit=1`. Leave the path empty to request the base URL. Select **Send test request** to see the HTTP status and response body.

The test uses unsaved connection settings and sends a real request. A test with `POST`, `PUT`, `PATCH`, or `DELETE` can change data in your API.

## Use a connection

In a Custom API action or widget's **Call API** function, select the connection, method, and **Path and query**. Add a JSON request body or choose **Query params** for the action's or function's fields when needed. The connection supplies the base URL, authentication, and headers.

You can edit a connection without changing its users. Its **Used by** list shows actions and widgets that use it. Remove the connection from each caller before deleting it.

For a complete setup, see [Custom API](/docs/actions/custom-api) or the [widget Call API guide](/docs/widgets/functions-and-states#call-api).