docs: document Cube token authentication for the Chat API

[paveltiunov]

Check List

• Tests have been run in packages where changes have been made if available
• Linter has been run for changed code
• Tests for the changes have been added if not covered yet
• Docs have been added / updated if required

Description of Changes Made (if issue reference is not provided)

Documents the recently added ability to authenticate Chat API requests with the deployment's own Cube token (JWT), as an alternative to API keys (implemented in cubedevinc/cubejs-enterprise#12808). Details verified against the enterprise implementation.

• docs-mintlify/reference/embed-apis/chat-api.mdx: splits the Authentication section into API key authentication (existing content) and a new Cube token authentication subsection — the deployment's Cube JWT (validated via the API secret, JWKS, or custom check_auth) passed in the X-Cube-Auth-Token header, with a required externalId claim (falling back to sub), a scope claim including chat, and an optional email claim. Covers Authorization header precedence, how the chat scope is asserted on the resolved security context with custom check_auth, that the caller's token is used as query credentials (so row-level security applies unchanged), how to enable the feature in deployment settings, and that sessionSettings is ignored with Cube token authentication. Also updates the abort endpoint's authentication note and the error-handling section (auth failures are returned as a JSON-RPC error object in an HTTP 200 response).
• docs-mintlify/api-reference/chat.yaml: registers a cubeToken security scheme (X-Cube-Auth-Token header) as an alternative to apiKey in the Chat API OpenAPI spec.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BfzMYkSrtEBV9ViFCyrePL

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Jul 10, 2026, 3:15 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude finished @paveltiunov's task in 44s —— View job

---

Code review

Docs-only change; content is clear and consistent with the rest of chat-api.mdx. A few small observations:

Nits (non-blocking)

• docs-mintlify/reference/embed-apis/chat-api.mdx:120 — the JS example references CUBE_TOKEN as a bare identifier. For parity with the API key example just above (which defines CHAT_API_URL), consider adding const CUBE_TOKEN = 'YOUR_CUBE_TOKEN'; so the snippet is copy-pasteable.
• docs-mintlify/reference/embed-apis/chat-api.mdx:6-10 — pre-existing, out of scope for this PR: the top-of-page plan-availability callout uses <Info>, but docs-mintlify/CLAUDE.md says plan-availability messages should use <Note> (gray) rather than <Info> (blue). Worth fixing in a follow-up.
• docs-mintlify/reference/embed-apis/chat-api.mdx:57 — pre-existing, out of scope: the API key example uses single quotes with ${API_KEY}, so the template literal is not actually interpolated. Should use backticks (the JS example lower in the file at line 1063 gets this right).

PR description flags for verification before merge (author already called these out):

• Exact JWT claim shape for the chat scope (scopes: ["chat"] vs. e.g. scope: "chat").
• Which token claims drive external-user provisioning — the docs say "external user and their security context are resolved from the token claims" without naming the claim(s); readers migrating from sessionSettings.externalId may want to know which JWT field maps to it.
• Whether enablement is truly support-gated or a self-serve deployment setting.

Positive

• OpenAPI spec correctly registers cubeToken as an alternative security scheme at both the global and per-operation level (chat.yaml:24-26, 215-217, 228-236).
• The row-level-security note (chat-api.mdx:151-153) is a valuable clarification — worth emphasizing since it's the main behavioral difference vs. API key auth.
• Abort endpoint's auth section and the 401 error description are correctly updated to mention both methods.

No blocking issues from a docs correctness standpoint.
• claude/chat-api-cube-token-docs-ky9io4

[claude]

Claude finished @paveltiunov's task in 34s —— View job

---

Code review (updated)

Re-reviewed after commit a3a3591, which changes the enablement wording from "contact Cube support" to "enable it in your deployment settings" in both chat-api.mdx:90-91 and chat.yaml:235. That resolves one of the three verification flags I raised previously (support-gated vs. self-serve). No other content changed.

Full review — 0 blocking, 3 nits (unchanged from prior pass)

Nits (non-blocking)

• docs-mintlify/reference/embed-apis/chat-api.mdx:120 — the JS example references CUBE_TOKEN as a bare identifier. For parity with the API key example above (which defines CHAT_API_URL), consider adding const CUBE_TOKEN = 'YOUR_CUBE_TOKEN'; so the snippet is copy-pasteable.
• docs-mintlify/reference/embed-apis/chat-api.mdx:6-10 — pre-existing, out of scope: plan-availability callout uses <Info>, but docs-mintlify/CLAUDE.md says these should be <Note> (gray) rather than <Info> (blue).
• docs-mintlify/reference/embed-apis/chat-api.mdx:57 — pre-existing, out of scope: API key example uses single quotes with ${API_KEY}, so the template literal is not interpolated. Should use backticks (the JS example at line ~1063 gets this right).

Verification flags still open (called out in PR description)

• Exact JWT claim shape for the chat scope (scopes: ["chat"] vs. scope: "chat").
• Which token claims drive external-user provisioning — docs say "external user and their security context are resolved from the token claims" without naming the claim(s).
• Whether enablement is support-gated or self-serve ✅ resolved in a3a3591 (self-serve via deployment settings).

Positive

• OpenAPI spec correctly registers cubeToken as an alternative security scheme at both global and per-operation level (chat.yaml:24-26, 215-217, 228-236).
• The row-level-security note (chat-api.mdx:151-153) is a valuable clarification — worth emphasizing since it's the main behavioral difference vs. API key auth.
• Abort endpoint's auth section and the 401 error description are correctly updated to mention both methods.

No blocking issues from a docs correctness standpoint.

• [`claude/chat-api-cube-token-docs-ky9io4`](https://github.com/cube-js/cube/tree/claude/chat-api-cube-token-docs-ky9io4)

[claude]

Claude finished @paveltiunov's task in 42s —— View job

---

Code review (updated after 9ab39c8)

Re-reviewed after the latest commit, which adds the externalId claim as a required token claim (in both chat-api.mdx:128-133 and chat.yaml:233-236) and updates the JWT example and rejection rules accordingly. That resolves the second of the three verification flags I flagged earlier (which claim drives external-user provisioning).

Full review — 0 blocking, 3 nits (unchanged from prior pass)

What's new in this commit

• chat-api.mdx:128-133 — token requirements are now enumerated as a bullet list (externalId + scopes), which reads more clearly than the prior single-sentence form.
• chat-api.mdx:140 — JWT sign() example now includes externalId: "user@example.com". The value shape matches the existing sessionSettings.externalId description at chat-api.mdx:169 ("lowercase and without spaces"), so callers migrating between the two auth modes get a consistent identifier contract. Good.
• chat-api.mdx:152-155 — external-user provisioning is now explicitly tied to the externalId claim rather than a vague "resolved from the token claims".
• chat-api.mdx:159-160 / chat.yaml:233-235 — rejection rules and OpenAPI security-scheme description both call out the missing-externalId case.

Nits (non-blocking, unchanged)

• chat-api.mdx:119 — the JS snippet still references CUBE_TOKEN as a bare identifier. For parity with the API key example (which defines CHAT_API_URL inline), consider adding const CUBE_TOKEN = 'YOUR_CUBE_TOKEN'; so the snippet is copy-pasteable.
• chat-api.mdx:6-10 — pre-existing, out of scope: plan-availability callout uses <Info>, but docs-mintlify/CLAUDE.md says these should be <Note> (gray).
• chat-api.mdx:57 — pre-existing, out of scope: API key example uses single quotes with ${API_KEY}, so the template literal is not interpolated. Should use backticks.

Verification flags

• Exact JWT claim shape for the chat scope ✅ resolved — scopes: ["chat"] (array) is now the documented shape in both the prose and the example.
• Which token claims drive external-user provisioning ✅ resolved in 9ab39c8 (externalId claim, matching sessionSettings.externalId).
• Support-gated vs. self-serve enablement ✅ resolved in a3a3591 (self-serve via deployment settings).

All three PR-description verification flags are now addressed.

Positive

• The externalId value contract is stated once (lowercase, no spaces) at chat-api.mdx:131-132 and matches sessionSettings.externalId at chat-api.mdx:169, so the two auth modes share a consistent identifier shape.
• Rejection rules are exhaustive: invalid-for-deployment, missing externalId, missing chat scope — each explicitly enumerated.
• OpenAPI cubeToken security-scheme description at chat.yaml:231-236 stays in sync with the prose docs.

No blocking issues from a docs correctness standpoint.

• [`claude/chat-api-cube-token-docs-ky9io4`](https://github.com/cube-js/cube/tree/claude/chat-api-cube-token-docs-ky9io4)

[claude]

Claude finished @paveltiunov's task in 1m 23s —— View job

---

Code review (updated after 25317d3)

Re-reviewed after the "apply enterprise review corrections" commit. This is a substantive round of implementation-verified fixes — the largest since the PR opened.

Full review — 0 blocking, 1 medium, 3 pre-existing nits

What changed in 25317d3

• chat-api.mdx:143 / chat.yaml:235 — scopes → scope (array). This resolves the exact-shape verification flag from the PR description.
• chat-api.mdx:139-142 — externalId semantics clarified: it's normalized to lowercase (not required to be lowercase input), and falls back to the standard JWT sub claim when absent. The rejection rule at chat-api.mdx:186-187 and OpenAPI description at chat.yaml:235 are updated in sync.
• chat-api.mdx:144-145 — new optional email claim documented.
• chat-api.mdx:129-134 — new <Warning> about Authorization header precedence: if both headers are sent, Authorization wins and X-Cube-Auth-Token is silently ignored. Important behavioral note for callers wiring up both paths.
• chat-api.mdx:90-92 — exact settings path (Settings → Configuration → Use Cube authentication for Chat and embedding APIs) instead of just "your deployment settings".
• chat-api.mdx:162-172 — new <Info> clarifying that chat is asserted on the resolved security context (i.e., after any check_auth rewrite), not the raw token payload. This is a subtle but load-bearing point for custom-auth deployments.
• chat-api.mdx:268-270 — sessionSettings reference entry now qualified as "required for API key authentication; ignored with Cube token authentication".
• chat-api.mdx:1142-1146 — 401 entry replaced with a new "Authentication errors" entry noting these come back as a JSON-RPC error inside an HTTP 200 response.

Medium — worth a follow-up

• chat-api.mdx:1142-1146 — the Error Handling section is now a mixed list: every other bullet is keyed by HTTP status code (400, 403, 404, 500), but "Authentication errors" is keyed by category and explicitly says the HTTP status is 200. Two consequences:

  1. Readers scanning for how to handle 401s (a very common pattern in client code) no longer find an entry.
  2. The section has effectively lost the "success = 200" ↔ "auth-failure = 200 with JSON-RPC error" contrast that a reader needs to build correct client behavior.

  Consider either restoring a **200 OK (with JSON-RPC error)**: authentication failures are returned as a JSON-RPC error object… style bullet, or moving auth-error handling out of the HTTP status list and into a short subsection that explicitly calls out the 200-with-error-body pattern. As written, a reader could easily miss that they must inspect the response body even on 2xx.

Nits (non-blocking, unchanged from prior passes)

• chat-api.mdx:120 — JS snippet references CUBE_TOKEN as a bare identifier. For parity with the API key example (which defines CHAT_API_URL inline at line 49), consider const CUBE_TOKEN = 'YOUR_CUBE_TOKEN'; so the snippet is copy-pasteable.
• chat-api.mdx:6-10 — pre-existing, out of scope: plan-availability callout uses <Info>, but docs-mintlify/CLAUDE.md explicitly says plan-availability callouts should use <Note> (gray) — "using a different color for plan gating makes it visually distinct and scannable".
• chat-api.mdx:57 — pre-existing, out of scope: API key example uses single quotes with ${API_KEY}, so the template literal isn't actually interpolated. Should use backticks (the Cube-token example on line 120 already gets this right by referencing the identifier directly).

Verification flags — all resolved

• Exact JWT claim shape for chat scope ✅ scope: ["chat"] (array) — corrected in this commit.
• Which claims drive external-user provisioning ✅ externalId with sub fallback — documented in this commit.
• Support-gated vs. self-serve enablement ✅ self-serve via deployment settings (path now explicit).

Positive

• The Authorization precedence warning at chat-api.mdx:129-134 is exactly the kind of detail that prevents silent misconfiguration bugs — worth having a <Warning> (not <Info>) here.
• The resolved-security-context <Info> at chat-api.mdx:162-172 correctly separates the mental model for default JWT vs. custom check_auth, which is a common source of confusion when scopes are involved.
• sessionSettings reference entry (chat-api.mdx:268-270) is now precisely conditional on auth mode, avoiding the ambiguity of "required" applying to both modes.
• OpenAPI cubeToken scheme description stays in sync with the prose throughout.

No blocking issues from a docs correctness standpoint. The Error Handling section drift is the one worth a small follow-up.

• [`claude/chat-api-cube-token-docs-ky9io4`](https://github.com/cube-js/cube/tree/claude/chat-api-cube-token-docs-ky9io4)