Skip to main content

Overview

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

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

In the Buckle dashboard, open Settings > Apps > Onyx and paste the key into API key or access token.
Buckle 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.

The Onyx connect window in Buckle.

Select Connect Onyx. Buckle 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.

What agents can do

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

Quick example

No Authorization header is needed, the gateway adds it:
For every endpoint, see the Onyx API docs or the OpenAPI explorer at https://cloud.onyx.app/api/docs.

Controlling access

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 Settings > Apps > 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

Create a new key in Onyx, then paste it into Settings > Apps > Onyx. Agents pick it up automatically. Then revoke the old key.
Store it in Buckle. The gateway injects it at the proxy, only on /api/ and /mcp/. See How it works.
Use an API key (service account) for a shared agent, or a personal token limited to read:search for an agent that only searches.