Frequently asked questions
Short answers about tenancy, auth, tickets, AI & KB Review, work boards, and the Agent API. Start with the AI & KB Review guide or full Docs.
What is Nexus?
A multi-tenant enterprise foundation for support tickets and work boards, with Identity/JWT, EF Core, MinIO, communications, and an Agent API for AI operators.
How is a tenant resolved on each request?
First match wins: (1) host mapping, (2) path /t/{slug}/… or /api/t/{slug}/…, (3) header X-Tenant-Slug or X-Tenant-Id. Tenant entities are isolated with EF global query filters.
What roles exist?
GlobalAdmin manages platform settings, tenants, and global users. TenantAdmin manages tenant brand, agent keys, and tenant communications overrides. User is a signed-in tenant member with access to boards and tickets according to product rules.
How do I log in from the SPA?
Username or email via POST /api/auth/login. The SPA stores access + refresh tokens; on 401 it refreshes once and retries. Access tokens are short-lived JWTs; refresh tokens rotate and are stored hashed.
What is the default seed admin in development?
When Seed:EnableRootAdminSeed is true and no global admins exist, a root admin is created (defaults often root / raven—override via config). Never enable root seed in production.
How does tenant branding work?
Tenant settings keys like brand.displayName, brand.logoUrl, brand.backgroundUrl, brand.primary, and brand.primaryForeground drive the shell. Empty values fall back to scaffold Raven assets and theme tokens. Anonymous clients can read brand via GET /api/config/brand.
What is a work “brand” vs shell brand?
Shell brand is login/chrome theme. Work brands are first-class entities under a tenant used for backlog and boards (/api/work/brands). They are different concepts and different APIs.
Can one work item sit on multiple boards?
Yes. Items may have multiple board placements. Lanes can optionally push item state via targetStateKey when moved.
How do agent API keys work?
Tenant admins create keys on /config/agent-api-keys. Keys are opaque values prefixed nxak_… (hash stored; plaintext shown once). Send X-Agent-Api-Key or Authorization: Bearer. Keys are bound to one tenant—host/path/header mismatch returns 403. Every /api/agent/* call is audited (no secrets or full bodies stored).
Where do agents discover endpoints?
Public (no auth): GET /api/agent/about. It returns catalog version, build number, endpoint list, and notes. Prefer /api/agent/work/* over human JWT routes so traffic is audited.
What is the difference between AI Review and KB Review?
AI Review is the live workflow for AI-generated draft replies: board view AI review, ticket tab AI draft—accept, edit, send, or reject. KB Review is knowledge curation: board view KB review, ticket tab KB review—grade staff answers, assign product, and promote gold public replies into product knowledge. They are independent; see the operator guide.
How do I process the AI review queue?
Go to Tickets → view AI review. Open a ticket with the “AI needs review” badge, read the draft on the AI draft tab, then Send, Accept (no send), or Reject. Use bulk Accept / Reject / Send drafts for multiple tickets. Details: AI Review how-to.
How do I promote a ticket answer into the knowledge base?
On the ticket KB review tab, assign a product, score the response, select the gold public message, and promote it. New knowledge is usually inactive with pending-curation. Activate it under Tickets → AI & knowledge. Step-by-step: Promote gold answers.
Where do I configure auto-send and the knowledge loop?
Tenant policy lives on Tickets → AI & knowledge (enabled, auto-send, min confidence, categories, citations, rescreen, KB loop). Platform worker mode/keys are under Admin → Platform settings or Tickets:AiScreeningWorker. See configure AI & knowledge.
Is AI ticket screening required?
No. Screening can be off, heuristic, or LLM. Platform worker settings and tenant AI policy control behavior. LLM mode needs an API key (e.g. env XAI_API_KEY or platform AppSettings).
What about secrets and configuration?
appsettings.Development.json is gitignored. Copy from the .example template. Deploy scripts do not overwrite server appsettings/nlog. Prefer platform settings UI for production runtime overrides where supported.
How do I verify the system is healthy?
GET /api/health is anonymous and includes version/buildNumber. Run dotnet test Nexus.slnx for backend coverage and Playwright e2e under Nexus.Web for UI smoke.
Who owns this product site?
This documentation site is hosted on Spider Silk at crow.illuminatingsoftware.com for the Nexus product (Illuminating Software / Orkboo).