Operator reference

API authentication and permissions

Overview of Nexus APIs

Before you begin

This reference describes the underlying platform. Use a Nexus school release with its school membership, class policy, and cost controls. Installing a base engine alone does not add those controls. Some options require a separately licensed feature. The presence of a guide does not unlock that feature.

Download the Nexus OpenAPI schema ↗
Import the schema into your API client. It describes the backend source; enabled routes depend on your workspace.

Nearly every Nexus feature is accessible through the Nexus API.

Nexus 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://school.narb.cc/api or https://your-self-hosted-onyx.com/api

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

This page applies to Nexus 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://school.narb.cc/api/me/permissions

Nexus 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 Nexus, 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 Nexus 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 Nexus 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://school.narb.cc/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 Nexus API endpoints. You can build request examples on the endpoint pages or follow one of our Guides.

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

the API reference in this documentation