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

# Search Company Knowledge in Onyx From Agents

> Let agents search company knowledge in Onyx, chat with Onyx agents, and manage documents. Connect an API key or access token the gateway keeps hidden.

## Overview

OneCLI connects AI agents to [Onyx](https://onyx.app) Cloud with an API key or personal access token. Agents can search the company knowledge Onyx has indexed, chat with your Onyx agents, and add documents through the ingestion API. The gateway injects the key into requests to `cloud.onyx.app`, so your agent never sees it.

This suits agents that need company context before they act: checking the runbook before touching production, or citing the policy doc behind an answer.

Connecting takes about a minute.

## What you will set up

* An Onyx API key or personal access token, scoped to what the agent needs
* Automatic key injection on the Onyx Cloud API and hosted MCP server
* Per-agent, per-tool access

## Connect Onyx

**1. Create a key in Onyx**

Onyx has two kinds of key. Pick the one that matches what the agent should reach.

| Key | Where to create it | What it reaches |
| - | - | - |
| **API key** | **Admin Panel** > **Service Accounts** (admins only) | Whatever the groups you assign to it allow. Each key is its own service account |
| **Personal access token** | **Settings** > **Accounts & Access** > **Create New Token** | Your own access, or less if you choose **Limited access** and pick scopes |

Copy the key right away. Onyx shows it only once.

> [!TIP]
>
> For an agent that only searches, create a service account in the **Basic** group, or a personal token limited to `read:search`. A key in the **Admin** group reaches every endpoint, including connector and user management.

**2. Paste it in OneCLI**

In the OneCLI dashboard, open **Connections** > **Onyx** and paste the key into **API key or access token**.

![OneCLI connect window for Onyx, showing the setup guide link, the API key or access token field with a How to create a key link, and the Connect Onyx button.](https://mintcdn.com/chartdbinc/7IV-es-83z77gSFO/images/integrations/onyx/onecli-connect-onyx.png?fit=max\&auto=format\&n=7IV-es-83z77gSFO\&q=85\&s=34a0caa4ddae44ced38d6563b0c4753e)

The Onyx connect window in OneCLI.

Select **Connect Onyx**. OneCLI checks the key with Onyx before saving it, so a wrong key is rejected right away.

> [!NOTE]
>
> This connection covers Onyx Cloud at `cloud.onyx.app`. The gateway adds the key only to the API (`/api/`) and the hosted MCP server (`/mcp/`), never to the Onyx web app on the same host. Self-hosted Onyx, which runs on your own domain, is not covered.

## What agents can do

| Area | What agents can do |
| - | - |
| **Search** | Search the documents Onyx has indexed from your connected sources, and read past searches |
| **Chat** | Start a chat session and send messages to an Onyx agent, list and read past sessions, and delete one |
| **Agents** | List and read Onyx agents (personas), and create, change, or delete them |
| **Documents** | List document sets and documents sent through the ingestion API, and add, update, or delete documents |
| **Connectors** | List connectors and their indexing status, create one, run it now, change it, or delete it |
| **Projects** | List and read projects |
| **MCP server** | Search and chat through the hosted Onyx MCP server at `cloud.onyx.app/mcp` |

The key's own Onyx permissions still apply. A Basic key can search and chat, but Onyx refuses its connector and admin calls whatever OneCLI allows.

## Quick example

No `Authorization` header is needed, the gateway adds it:

```bash theme={null}
# Search company knowledge
curl -s -X POST "https://cloud.onyx.app/api/search/send-search-message" \
  -H "Content-Type: application/json" \
  -d '{"search_query": "on-call escalation policy"}'

# Check what this key can do
curl -s "https://cloud.onyx.app/api/me/permissions"
```

For every endpoint, see the [Onyx API docs](https://docs.onyx.app/developers/overview) or the OpenAPI explorer at `https://cloud.onyx.app/api/docs`.

## Controlling access

[Grant](https://onecli.sh/docs/guides/agent-access.md) the connection to each agent that needs it, and choose per tool what runs freely, what needs approval, and what's blocked.

A good default is to let agents search freely and gate everything else. **Chat with Onyx** spends your Onyx LLM budget on every message, and the ingestion and connector tools change what every Onyx user finds when they search, so put those behind approval or block them.

Organization [rules](https://onecli.sh/docs/guides/rules.md) add guardrails on top. A blocked request never reaches Onyx.

To disconnect, remove the connection in **Connections** > **Onyx**, then revoke the key in Onyx: under **Admin Panel** > **Service Accounts** for an API key, or **Settings** > **Accounts & Access** for a personal token.

## FAQ

> [accordion] How do I rotate my Onyx key?
>
> Create a new key in Onyx, then paste it into **Connections** > **Onyx**. Agents pick it up automatically. Then revoke the old key.

> [accordion] How do I keep the key out of the agent's context?
>
> Store it in OneCLI. The gateway injects it at the proxy, only on `/api/` and `/mcp/`. See [How it works](https://onecli.sh/docs/how-it-works.md).

> [accordion] API key or personal access token?
>
> Use an API key (service account) for a shared agent, or a personal token limited to `read:search` for an agent that only searches.


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