Overview & Auth

Overview of Onyx APIs

Nearly every Onyx feature is accessible through the Onyx API.

Onyx APIs are built on REST principles with JSON request/response formats. All endpoints require authentication and follow relatively consistent patterns.

Make API requests to:

https://cloud.onyx.app/api or https://your-self-hosted-onyx.com/api

Onyx follows SemVer 2.0.0. Breaking changes will be indicated by major version increments.

This page applies to Onyx v4.7 and later, which replaced API key roles with group-based permissions. For older versions, see Overview & Auth before v4.7.

Authentication

Every request authenticates with a Bearer token in the Authorization header:

curl -H "Authorization: Bearer <token>" \
  https://cloud.onyx.app/api/me/permissions

Onyx has two kinds of token. An API Key belongs to a service account. A Personal Access Token belongs to you.

API Keys

API Keys are created by admins from the Admin Panel. Each key exists as a distinct service account user in Onyx, so you can trace activity, keep chat sessions private, and scope resources to a specific key.

A service account has no permissions of its own. Its access comes from the groups you assign to it when you create the key.

Groups assigned	What the key can do
None	Chat only. It can create sessions and send messages, but it cannot search and cannot reach any admin endpoint.
Basic	Chat, search, projects, and its own agents.
Admin	Every endpoint, including the ones prefixed with admin/.
A custom group	Whatever that group grants. A group with Manage Connectors & Document Sets, for example, unlocks the connector and document set endpoints.

Permissions add together. A key in several groups receives the union of their permissions.

A key in the Admin group has unrestricted access to your Onyx instance. Prefer a group that grants only the permissions your integration needs.

Custom groups and configurable group permissions are an Enterprise Edition feature.

See Service Accounts for setup instructions.

Personal Access Tokens

Personal Access Tokens (PATs) let a user authenticate API requests as themselves.

To create a token, go to Settings > Accounts & Access and click Create New Token. Give it a name, choose an expiration (7 days, 30 days, 365 days, or never), and choose its permissions:

Permissions	Behavior
Full access	The token inherits all of your permissions.
Limited access	The token is capped to the scopes you select.

A limited token can pick from these scopes:

Scope	Permission	Allows
Search — Read	read:search	Use the search and web search endpoints.
Chat — Read	read:chat	View chat sessions and messages.
Chat — Write	write:chat	Create sessions and send messages. Includes Chat — Read.
LLM Gateway — Use	use:llm_gateway	Call the LLM Gateway from external tools. Enterprise Edition.

Scopes only narrow access. A limited token receives the scopes you selected and your own permissions, never more than you can do yourself. A limited token is also rejected on any endpoint outside its scopes, even one you can reach in the browser.

Creating a token requires the Create User Access Token permission, which an admin grants to a group. Admins always have it.

Your token is displayed only once at creation. Copy it immediately and store it securely.

You can view, audit, and revoke your tokens at any time from Settings > Accounts & Access.

Permissions

Every endpoint page in the API Reference states the permission it requires. Permissions come from the groups a user or service account belongs to: basic from the Basic group that every user joins, and admin from the Admin group, which passes every check.

This permission model applies to Onyx v4.7 and later. For how groups, group permissions, and Group Managers work, see Understanding Permissions.

Endpoint pages and GET /me/permissions identify a permission by its value. Each value maps to a permission an admin grants to a group in the Admin Panel:

Admin Panel	Permission
Manage LLMs	manage:llms
Manage Connectors & Document Sets	manage:connectors, manage:document_sets
Manage Actions	manage:actions
Manage Groups	manage:user_groups
Manage Service Accounts	manage:service_account_api_keys
Manage Slack/Discord Bots	manage:bots
Create Agents	add:agents
Manage Agents	manage:agents
View Agent Analytics	read:agent_analytics
View Query History	read:query_history
Create User Access Token	create:user_api_keys

A management permission also grants the reads it needs — manage:connectors includes read:connectors — so a caller resolves to more permissions than were granted.

Checking what a token can do

GET /me/permissions returns the caller’s resolved permissions:

curl -H "Authorization: Bearer <token>" \
  https://cloud.onyx.app/api/me/permissions

{
  "permissions": ["basic", "manage:connectors", "read:chat", "read:connectors", "..."],
  "is_manager": false,
  "managed_group_ids": []
}

A request that fails a permission check returns 403:

{
  "error_code": "INSUFFICIENT_PERMISSIONS",
  "detail": "You do not have the required permissions for this action."
}

API Reference and Playground

In the API Reference, we have curated a subset of useful Onyx API endpoints. You can experiment with the endpoints on each page or follow one of our Guides.

You can find all Onyx API endpoints in the built-in OpenAPI explorer:

https://cloud.onyx.app/api/docs or https://your-onyx-domain.com/api/docs

The explorer is purely for reference. It is not a fully-featured API client. Ignore the tenant_id parameter and use your API key as a Bearer token.

Next Steps

Core Concepts

Learn the fundamental concepts and terminology for working with Onyx APIs

Guide: Send a Chat Message

Simple example of sending a message programmatically