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"
}

Docker Compose

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

Anonymous users

If a request is made without an authenticated user, Onyx sends "user": "anonymous_user". Because anonymous_user is not a valid email address, CoreCube rejects it with 400 INVALID_USER_IDENTITY — the value fails email validation before any user lookup, so it can never be matched to an account or auto-provisioned. (A genuine unmatched email returns 404 USER_NOT_FOUND, not 403.) 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.

Auto-provisioned users

Auto-provisioned users receive a no_access role and the default scope only. They cannot log into the CoreCube admin console. 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.

Requests fail with 400 MISSING_USER SEND_USER_METADATA_TO_LLM_PROVIDER is false or not set, so the user field is absent from the request body. CoreCube rejects the request with 400 MISSING_USER (message: Request body field user is required) — it does not fall back to the service key owner's scopes. Set the env var and restart Onyx.