> ## Documentation Index > Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt > Use this file to discover all available pages before exploring further. # Custom Connections: Connect Any API With a Key > Connect any API that uses an API key or secret, even without a built-in OneCLI app. Approve it from your agent's chat or add it in the dashboard. The gateway injects the key, so the agent never sees it. A custom connection lets your agents call any API that uses an API key or secret, even if OneCLI has no built-in app for it. You store the key once. The gateway adds it to matching requests, so the agent never sees it. There are two ways to add one: * **From the chat.** Your agent proposes the connection and you paste the key into a card. * **From the dashboard.** You fill in the **Custom connection** form yourself. ## Approve a connection from the chat Ask your agent for what you need, for example "check my campaigns in AcmeCRM". If there is no built-in app, the agent researches the API on its own and proposes a connection. A card appears in the chat: ![A custom connection card in the OneCLI chat, asking to connect an app, with a field for the API key](https://mintcdn.com/chartdbinc/OBBGs4ET8TUOlmwE/images/custom-connections/onecli-agent-proposes-custom-connection.png?fit=max\&auto=format\&n=OBBGs4ET8TUOlmwE\&q=85\&s=a2b4f1a6585f5d62d59ed119d9183480) | Part of the card | What it means | | - | - | | **Connect *app name*?** | The app the agent wants to connect | | **Your key will be sent to** | The only domain the key is sent to. Check it matches the service you expect | | **Key field** | Paste the API key from the service here. Click the eye icon to show or hide it | | **Need help?** | Opens this page | | **Decline** | Rejects the proposal. Nothing is saved | | **Approve** | Saves the key and connects the app. Enabled once a key is pasted | After you approve, the agent is told the connection is ready and continues your request. > [!NOTE] > > Paste the key into the card, never into the chat message box. The key goes straight to encrypted storage. It never passes through the agent and is never saved in the chat history, approvals, or audit log. If you pasted a key into a chat message by mistake, revoke it in the service and add a new one. A connection you approve from the chat is turned on only for the agent that asked for it. Turn it on for other agents from their **Connections** page. ## Add a connection in the dashboard Open the form in one of two ways: * Go to **Connections** → **Custom** and click **Add connection**. * On an agent's page, open **Connections** → **Custom** and click **Add connection**. The new connection is turned on for that agent. ![The Custom connection form in the OneCLI dashboard](https://mintcdn.com/chartdbinc/OBBGs4ET8TUOlmwE/images/custom-connections/onecli-custom-connection-form.png?fit=max\&auto=format\&n=OBBGs4ET8TUOlmwE\&q=85\&s=b58b7995e819d962410764b2151b0846) ### Try an example Click **Airtable**, **Google Maps**, or **Telegram Bot** to fill in the form with a real API. Each one uses a different way of sending the key: | Example | API host | Sent as | | - | - | - | | **Airtable** | `api.airtable.com` | **Bearer token** | | **Google Maps** | `maps.googleapis.com` | **URL parameter** named `key` | | **Telegram Bot** | `api.telegram.org` | **URL path** with the template `/bot{value}` | The example fills in everything except the key. Paste your own key to save it. ### Fields | Field | What to enter | | - | - | | **Name** | A name you and your agents will recognize, for example `Airtable` or `Airtable - Marketing`. | | **API key / Secret** | The key from the service. It is encrypted and never shown again. When editing, leave it empty to keep the current key. | | **API host** | The API's hostname only, for example `api.airtable.com`. No `https://` and no path. Use `*.example.com` to cover every subdomain. | | **Sent as** | Where the gateway puts the key in each request. See below. | | **Limit to a path (optional)** | Use the key only for matching paths, for example `/v1/*`. Leave it closed to use the key on every path of the host. | ### Sent as Pick the option the service's API docs describe. The form shows a preview of exactly what the gateway sends, with the key masked. > [tab] Bearer token > > The default, and the most common option. The gateway sends: > > ```text theme={null} > Authorization: Bearer •••••• > ``` > > Use it when the docs mention a "Bearer token" or the `Authorization` header. > [tab] Custom header > > The key goes in a header with a name you choose. > > | Field | What to enter | > | - | - | > | **Header name** | The header from the docs. Defaults to `X-Api-Key` | > | **Value format (optional)** | Text around the key, for example `Token {value}`. Put `{value}` where the key goes | > > Example preview: `X-Api-Key: ••••••` > [tab] URL parameter > > The key goes in the query string of every request. > > | Field | What to enter | > | - | - | > | **Parameter name** | The parameter from the docs. Defaults to `api_key` | > | **Value format (optional)** | Text around the key. Put `{value}` where the key goes | > > Example preview: `?api_key=••••••` > [tab] URL path > > The key is part of the URL path, as in the Telegram Bot API (`/bot/getMe`). Choose a **Mode**: > > | Mode | Fields | How it works | > | - | - | - | > | **Template** | **Path template**, for example `/bot{value}` | Put `{value}` where the key goes. The gateway replaces whatever the agent sends in that spot, up to the next `/`, so the agent never needs the real key | > | **Regex** | **Path pattern (regex)**, for example `^/bot[^/]+(/.*)?$`, and **Replacement**, for example `/bot{value}$1` | For paths a template can't describe. Use `$1` for capture groups and `{value}` for the key | > > The preview shows what the agent sends and what the gateway sends instead. In template mode, click **Copy call** to copy an example URL. > > **Limit to a path** is hidden for this option, because the path is already part of the setup. ### Save it Click **Add connection**. A connection added from **Connections** → **Custom** isn't turned on for any agent yet. Choose which agents can use it from the connection's agent list or from each agent's **Connections** page. ## Several accounts on the same API You can add more than one connection for the same host, for example two Airtable accounts. When an agent calls that API and more than one connection matches, the gateway asks it to choose. The agent picks the right one for each request, so it can use both accounts in the same task. ![An agent's Custom connections tab with several custom connections, two of them on the same host](https://mintcdn.com/chartdbinc/OBBGs4ET8TUOlmwE/images/custom-connections/onecli-agent-multiple-custom-connections.png?fit=max\&auto=format\&n=OBBGs4ET8TUOlmwE\&q=85\&s=bbf8e69ffaf6499c20b1f301c25aaf27) Give each connection a clear name, such as `Airtable - Sales` and `Airtable - Marketing`, so you and the agent can tell them apart. A workspace connection takes priority over an organization one. A connection limited to a path takes priority over one for the whole host. ## Edit or remove a connection Click the pencil icon on **Connections** → **Custom**, or on an agent's **Connections** → **Custom** tab, to rename a connection or replace its key. When you replace a key, every agent keeps its current access. Delete a connection from **Connections** → **Custom**. ## Limitations * **HTTP Basic auth isn't supported yet.** APIs that log in with a username and password pair, sent as `Authorization: Basic …`, can't be connected as a custom connection. * **Built-in apps come first.** If OneCLI has a built-in app for the service, use it from [App Connections](https://onecli.sh/docs/integrations/app-connections.md) instead. ## Security * Keys are encrypted at rest and decrypted only by the gateway, at request time. * Agents never see the key. They make normal requests and the gateway adds it. * The key is sent only to the host you set, never to other domains. * [Rules](https://onecli.sh/docs/guides/rules.md) apply to custom connections too: block requests, require approval, or set rate limits. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.