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 Engineering Glossary is the authoritative source for contributors. If the two disagree, fix the mismatch before release.

• 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.

• 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.

• 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.

• 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.

• 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.

• Tier 1 telemetry — Tenant-visible analytics: request rows in ClickHouse surfaced through the console request, session, and usage pages. See the telemetry contract in the vortex-common-crates repository.
• Tier 2 telemetry — Operator OTLP telemetry per the same contract. Collector containers run in Compose; full per-service instrumentation varies.
• HQL — Query language for analytics, served by the query service (POST /api/hql) and available from the console.

• Audit event — A record of who did what, when, sealed into the tamper-evident audit log. See the audit event contract in the vortex-common-crates repository. 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.

• 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 your synced registry (just models-sync). The official OpenAI and Anthropic SDKs are the supported client libraries; no separate first-party SDK is required.

• “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.