User Glossary

This glossary explains terms for users and operators of nexus as it exists in the open-source tree today: the nexus CLI, the nexus ops serve / nexus-gateway OpenAI-compatible edge, and the full Compose stack (control-plane, auth, policy, ingest, trace-ingest, audit, query, and the console). Expand this file in the same MR that adds a new user-facing surface.

The engineering glossary at ../glossary.md is the authoritative source for contributors. If the two disagree, fix the mismatch before release.

Tenants, workspaces, organizations, projects, and keys

• Tenant — The account boundary for sign-in, billing, and data isolation. A hosted deployment may map each tenant to its own subdomain.
• Workspace — A grouping inside a tenant (nexus workspaces create). It owns organizations, workspace memberships, the wallet used for pass-through billing, and workspace-scoped audit views.
• Organization — A grouping inside a workspace (nexus orgs create --workspace <ref>; the workspace is required). It owns projects and organization-level settings.
• Project — A workload scope inside an organization (nexus projects create). API keys, provider keys, and usage are scoped to a project.
• Member roles — Each membership carries a role: Manager (administers the organization, projects, members, and settings), Auditor (everything a User can do, plus viewing the audit log), or User (self-service member with their own API keys).
• API key — A secret you mint with nexus credentials api-keys create, sent as Authorization: Bearer nxs_... to the gateway. Only a hash plus prefix is stored after creation.
• Personal developer key — A user-bound nxd_... secret minted from Account in the console. It authenticates Query and Trace HTTP APIs as you, with optional project scope and least-privilege permissions. It is not valid for gateway model traffic. On a Traefik deployment, mint keys on the console hostname; call Query only where your operator publishes Query HTTP. See ../dev/personal-developer-keys.md.

How your requests are routed

• BYOK (Bring Your Own Key) — You register an upstream provider secret with nexus credentials provider-keys create. The gateway forwards chat completions using that credential; your upstream provider bills you.
• PTB (Pass-Through Billing) — nexus-held provider credentials with consolidated billing. Enabled by the operator via NEXUS_GATEWAY_PTB=1; requires a funded workspace wallet.
• Platform provider key — An operator-managed upstream provider secret for PTB, distinct from a tenant BYOK provider key. Manage platform keys with nexus credentials platform-keys set/list/rm/rotate; scoped keys resolve from project to org to workspace to tenant/global fallback.
• Fallback — Automatic cross-provider retries against alternate endpoints/models. Controlled by the nexus-fallback header or comma-separated model strings; caller-authored order is preserved (only canonical-model fan-out across providers is cost-sorted).
• Attempt — One upstream HTTP call for a client request. The gateway walks the attempt list in order; on failure before any client bytes, the next attempt is tried.
• Registry artifact — A canonical manifest plus JSONL datasets containing reviewed model, endpoint, capability, pricing, removal, and source evidence. Dataset and whole-artifact SHA-256 digests detect changes; operators may require an Ed25519 signature from a trusted key.
• Import change set — The persisted review record produced by comparing one validated registry artifact with the current provider baseline. Approval is time-limited and bound to the exact artifact, baseline, findings, schema, contract, and generator before atomic application.

Grouping and tagging requests

• Session — Logical grouping of requests via nexus-session-* headers (nexus-session-id, optionally nexus-session-path and nexus-session-name). Sessions appear in the console with a list, per-session timeline, and live view.
• Property — Custom dimensions via nexus-property-* headers. Ignored by the current gateway handler.
• Reporting dimension — A workspace manager can define a named reporting value and assign it to an API key. Each request records the assigned value at completion, so reports retain the original value after the key is renamed or revoked. Do not use reporting metadata for secrets.

Data handling

• Classification — Sensitivity label carried on nexus-classification. The label vocabulary is configured per workspace as an ordered list (new workspaces start with public, internal, confidential, restricted) and refined by organizations and projects, which can add labels and tighten their own default and ceiling. Unlabeled requests take the scope’s default label, labels outside the vocabulary are rejected, and requests whose label is above the scope’s classification ceiling are denied.
• Redaction — Removing sensitive fields before persistence. The shipped policy obligation redacts email-like strings; broader redaction pipelines are not implemented.
• Retention — How long records live. The audit service seals events into Postgres plus a write-once object-store archive; the local dev audit.log file grows until you rotate or delete it. Analytics and object-store retention are operator-configured.
• Body storage — When trace capture is enabled (per org/project/API key or the nexus-enable-tracing header), request/response bodies are compressed and written to object storage and served back through authenticated query APIs. With capture disabled, only metadata rows are kept.

Quotas and billing

• Rate limit — Requests-per-window caps. Enforced by the gateway via a Redis-backed fixed-window counter per API key (RPS + RPM) when a Redis-compatible cache is configured. Returns HTTP 429 with Retry-After.
• Usage — Token counts and cost estimates parsed from upstream responses where available; stored on request rows and monthly rollups, surfaced in the console usage dashboard and in gateway.request.completed audit events.
• Budget — Spend caps at workspace, organization, and project level, configured in the console Limits pages and enforced by the gateway against monthly usage snapshots.

Telemetry and dashboards

• Tier 1 telemetry — Tenant-visible analytics per ../../vortex-common-crates/contracts/telemetry.md: request rows in ClickHouse surfaced through the console request, session, and usage pages.
• Tier 2 telemetry — Operator OTLP telemetry per the same contract. Collector containers run in Compose; full per-service instrumentation varies.

Audit

• Audit event — A record of who did what, when, sealed into the tamper-evident audit log described in ../../vortex-common-crates/contracts/audit-event.md. Managers and auditors browse these in the console’s Audit page for their organizations and workspaces.
• Audit log viewer — The console pages at /o/<org>/audit and /w/<workspace>/audit that list audit events with kind, classification, and time-range filters. Viewing audit data is itself recorded as an audit event.
• Inclusion proof — A downloadable cryptographic proof that an audit event is sealed in the log and has not been altered. Available from the event detail drawer once an event is sealed; verifiable with the nexus-audit-verify tooling in this repository.

SDKs and integrations

• Drop-in compatibility — Point an unmodified official SDK at nexus by changing only its base URL and API key: OpenAI SDKs use base_url → the gateway’s /v1 edge, Anthropic SDKs (and Claude Code) use ANTHROPIC_BASE_URL → the /anthropic edge, both with nxs_... keys against any model in the applied registry. The official OpenAI and Anthropic SDKs are the supported client libraries; no separate first-party SDK is required.

Terminology hygiene

• “Immutable” — We do not use this marketing term. Prefer tamper-evident; verification ships as the nexus-audit-verify tool and inclusion-proof downloads.
• Prompt-complexity tiers (T1 / T2 / T3) — Client-side helpers; do not confuse them with data-sensitivity Classification.