OneCLI connects AI agents to Onyx 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.
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.
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.
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.
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.
Grant 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 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.
