Onyx

Onyx (formerly Danswer) is a self-hosted enterprise AI platform. When configured as a custom LLM provider pointing to CoreCube, Onyx forwards the logged-in user's email in the standard OpenAI user request body field — CoreCube reads this to apply per-user knowledge scoping.

Prerequisites

• CoreCube running and accessible from your Onyx instance
• An admin account on CoreCube

Step 1 — Create a service API key

In the CoreCube admin console, go to Settings → API Keys and create a new key:

Field	Value
Key Name	Onyx Production (or any label)
Key Type	Service — proxy app
Integration	Onyx
Owner User	Select an admin user as key owner
Auto-provision users	Enable if you want CoreCube to create accounts automatically for new Onyx users
Default scope	Select the scope new users should receive (required when auto-provision is on)

Save the key — copy the raw value now, it is shown only once.

Step 2 — Enable user metadata forwarding in Onyx

Set the following environment variable on your Onyx backend:

SEND_USER_METADATA_TO_LLM_PROVIDER=true

With this enabled, Onyx includes the logged-in user's email in the user field of every chat completions request body:

{
  "model": "...",
  "messages": [...],
  "user": "alice@company.com"
}

:::info Docker Compose

services:
  onyx-backend:
    environment:
      SEND_USER_METADATA_TO_LLM_PROVIDER: 'true'

:::

:::note Anonymous users If a request is made without an authenticated user, Onyx sends "user": "anonymous_user". CoreCube will reject this with 403 USER_NOT_FOUND unless you have an account with that email or auto-provision is enabled. Anonymous usage is not recommended for production deployments. :::

Step 3 — Add CoreCube as a custom LLM provider in Onyx

In Onyx admin, go to LLM Providers and add a new custom provider:

Field	Value
Provider name	CoreCube
Base URL	http://corecube:7400/v1 (or your CoreCube address)
API key	The service key from Step 1
Model names	Models from your CoreCube LLM provider configuration

Step 4 — Ensure users exist in CoreCube

CoreCube resolves the user from the user body field. Each Onyx user must have a matching account in CoreCube with the same email address.

Option A — Manual: Create users in CoreCube admin (Settings → Users) with matching email addresses.

Option B — Auto-provision: Enable the auto-provision toggle on the service key (Step 1). New users are created automatically on their first query.

:::warning Auto-provisioned users Auto-provisioned users receive a viewer role and the default scope only. Adjust their scope and role in CoreCube admin after provisioning if needed. :::

Step 5 — Assign knowledge scopes

In CoreCube admin, go to Access Control → Scopes and assign each user to the appropriate scope. Users without a scope assignment will receive empty search results.

How it works end-to-end

Alice logs into Onyx
  → sends a chat message
  → Onyx calls POST /v1/chat/completions
    with: Authorization: Bearer cc_SERVICE_KEY
          body: { ..., "user": "alice@company.com" }
  → CoreCube reads body.user, resolves alice, applies her scopes
  → searches only compartments alice can access
  → returns cited response

Troubleshooting

"User not found" errors The email in Onyx does not match any CoreCube user. Ensure SEND_USER_METADATA_TO_LLM_PROVIDER=true is set and Onyx has been restarted. Check that email addresses are identical in both systems.

"user": "anonymous_user" in requests The Onyx user making the request is not authenticated or Onyx cannot resolve their identity. Ensure users are properly logged into Onyx before querying.

All users see the same results SEND_USER_METADATA_TO_LLM_PROVIDER is false or not set. The user field will not be present in requests, and CoreCube will fall back to the service key owner's scopes.