Platform Administration

Guide for platform administrators

Last updated on: August 7, 2026

This guide covers platform administration tasks for Nexus, including managing workspaces, configuring authentication, setting up provider integrations, and maintaining system health.

Overview

Platform administrators are responsible for the full lifecycle of Nexus deployment and tenant operations. This includes creating and configuring workspace and organization management to establish proper tenant boundaries and isolation, setting up authentication and access controls by configuring SSO/OIDC integrations, managing user registration modes, and overseeing the complete user lifecycle from onboarding to offboarding. Administrators also configure provider integrations to establish AI provider connections using both Bring Your Own Key (BYOK) and Platform-Provisioned Billing (PTB) models, manage billing and wallets by configuring payment processing systems and distributing platform credits across teams, enforce security and compliance requirements through data classification policies, tamper-evident audit trails, and policy-based access controls, and maintain system health through continuous monitoring using health checks, metrics collection, and observability tooling.

Managing Workspaces and Organizations

Nexus uses a hierarchical structure to organize resources and enforce isolation: tenant → workspace → organization → project. At the top level, a tenant represents a single Nexus deployment instance with its own database, authentication realm, and infrastructure resources. Within each tenant, workspaces provide the primary isolation boundary for different business units, customers, or departments, each with completely separate billing, access control, and security policies. Organizations sit within workspaces and group related teams or functional areas, inheriting workspace-level policies while allowing additional restrictions. Finally, projects are the operational units where actual work happens—they contain API keys, provider credentials, model configurations, and artifacts, and serve as the scope for most day-to-day development activities.

Workspace Management

Workspaces are top-level tenant boundaries that provide complete isolation between different business units, customers, or organizational divisions. Each workspace operates as an independent environment with its own wallet for billing and cost allocation, its own classification policy defining how sensitive data is labeled and protected (such as public, internal, confidential, and restricted tiers), and its own member roster controlling which users have access and what roles they hold. This isolation ensures that spending, security policies, and access controls never leak across workspace boundaries—for example, a workspace for the finance team cannot see or access resources belonging to the engineering team’s workspace, even though both exist within the same Nexus tenant. Workspaces also maintain separate audit trails, allowing compliance teams to scope investigations and export audit data per business unit without commingling records from unrelated teams.

Create a workspace:

nexus workspaces create \
  --slug acme \
  --name "Acme Corporation" \
  --created-by user@acme.com

List workspaces:

nexus workspaces list

Update classification policy:

nexus workspaces update acme \
  --classification-tiers "public,internal,confidential,restricted" \
  --default-classification internal \
  --classification-ceiling confidential

See Data Classification for details on classification lattices.

Organization Management

Organizations group related projects within a workspace, providing a logical boundary for teams, departments, or functional areas that need to collaborate under shared policies. They inherit the workspace’s classification settings, including the defined classification tiers and default labels, but can tighten the classification ceiling to impose stricter controls. For example, if a workspace allows classification levels from public up to restricted, an organization within that workspace might set its ceiling at confidential, preventing any projects in that organization from being labeled as restricted. This inheritance model allows platform administrators to set baseline security policies at the workspace level while giving organizational leads the flexibility to apply more restrictive controls based on their team’s risk profile or compliance requirements. Organizations cannot relax workspace policies—only tighten them—ensuring a consistent security baseline across the entire workspace.

Create an organization:

nexus orgs create \
  --workspace acme \
  --slug engineering \
  --name "Engineering Team"

List organizations:

nexus orgs list --include-inactive

Remove an organization:

nexus orgs rm acme/engineering --cascade

The --cascade flag deletes all child projects. Organizations are soft-deleted by default (recoverable).

Project Management

Projects are the working scope for API keys, provider keys, and artifacts, representing the operational context where developers and applications interact with Nexus. Each project acts as an isolated container that holds API keys for authentication, provider keys (such as OpenAI or Anthropic credentials) for accessing AI models, and artifacts like generated prompts, model outputs, and configuration files. Projects define the scope for access control, billing attribution, and audit logging—when a user or application makes a request, it’s always done in the context of a specific project, which determines what resources they can access, what classification labels apply, and which wallet gets charged. This project-scoped model enables fine-grained resource isolation, so different applications or teams can share an organization while maintaining separate API keys, provider configurations, and cost tracking. Projects also serve as the boundary for rate limits, quota enforcement, and usage analytics, making them the fundamental unit of operational control in Nexus.

Create a project:

nexus projects create \
  --org acme/engineering \
  --slug ml-pipeline \
  --name "ML Pipeline"

List projects:

nexus projects list --org acme/engineering --include-inactive

Remove a project:

nexus projects rm acme/engineering/ml-pipeline --cascade

Membership Roles

Members can be assigned one of three roles at the workspace, organization, or project level, each granting different capabilities and access rights. The manager role provides full administrative access, allowing members to manage other members and their role assignments, modify workspace or organization settings including classification policies, configure billing and wallet allocations, create and delete projects, and make any configuration changes needed to operate the environment. The auditor role grants read-only access to audit logs and compliance reports, enabling security and compliance teams to review system activity, export audit data, verify cryptographic integrity, and generate compliance reports without the ability to modify any settings, users, or resources—this role is specifically designed for separation of duties in regulated environments. The user role provides self-service access to assigned projects, allowing members to create API keys, configure provider integrations, make API requests, and view usage data within their projects, but preventing them from managing other users or modifying workspace-level or organization-level policies.

Role inheritance follows the organizational hierarchy: workspace manager memberships automatically extend to all child organizations and projects, so a workspace manager has full administrative access across the entire workspace without needing explicit role assignments at lower levels. Similarly, organization managers inherit access to all projects within their organization. This hierarchical inheritance simplifies administration by allowing broad access grants at higher levels while still supporting fine-grained permissions when needed—for example, a user might have manager access to one specific project but only user access to others in the same organization.

REST API for membership management:

PATCH /api/workspaces/:workspace_id/classification
PATCH /api/orgs/:org_id/classification
PATCH /api/projects/:project_id/limits

Authentication and Access Control

Single Sign-On (SSO) with OIDC

Nexus supports OIDC-based federated sign-in with Google Workspace, Microsoft Entra ID (formerly Azure AD), and any generic OIDC-compliant identity provider, enabling organizations to leverage their existing identity infrastructure for authentication and single sign-on. This integration allows users to authenticate using their corporate credentials without creating separate passwords for Nexus, centralizing identity management in your organization’s primary identity provider. The OIDC implementation uses the Authorization Code flow with PKCE (Proof Key for Code Exchange) for enhanced security, supports just-in-time user provisioning to automatically create accounts on first login, and provides identity resolution through issuer and subject claims to reliably link OIDC identities to Nexus user accounts. Organizations can enforce email domain allowlists to restrict access to specific domains (such as @acme.com), and all authentication events generate detailed audit logs for compliance tracking. This federated approach reduces password fatigue, improves security by eliminating credential reuse, and enables centralized access revocation—when a user is removed from your identity provider, they immediately lose access to Nexus.

Configuration (environment variables):

# OIDC Provider Settings (set per deployment)
AUTH_OIDC_PROVIDER_NAME=google
AUTH_OIDC_CLIENT_ID=...
AUTH_OIDC_CLIENT_SECRET=...
AUTH_OIDC_ISSUER_URL=https://accounts.google.com
AUTH_OIDC_REDIRECT_URL=https://nexus.acme.com/auth/callback

# Policy
AUTH_OIDC_LINK_BY_EMAIL=true  # Auto-link existing users by email

Key features:

Authorization Code flow with PKCE
Just-in-time user provisioning (auto-creates Personal Workspace on first sign-in)
Identity resolution via user_identities(issuer, subject)
Email domain allowlists (server-side enforcement)
Audit events: auth.oidc.login_started, login_succeeded, login_denied

Technical details: See OIDC Federated Sign-In for implementation specifics.

Planned features (not yet implemented):

Per-workspace OIDC connections (stored in DB with KMS-wrapped secrets)
Subdomain-based SSO entrypoints
SCIM provisioning
SAML support

Registration Modes

Control who can sign up for your Nexus deployment through registration modes that balance accessibility with security. Platform administrators can configure one of three registration modes to match their organization’s access control requirements: open registration allows anyone to create an account, which is useful for public-facing deployments or internal environments where broad access is acceptable; invite-only mode requires users to have a valid registration code or membership invitation before creating an account, providing a middle ground that allows controlled onboarding while still supporting self-service signup; and closed registration completely disables self-service account creation, requiring administrators to manually create all user accounts, which is appropriate for highly regulated environments or deployments where every user must be explicitly vetted. These modes can be combined with email domain restrictions and OIDC federation to create layered access controls—for example, you might enable open registration but restrict it to users with email addresses from your corporate domain who authenticate through your SSO provider.

# Open registration (anyone can sign up)
AUTH_ALLOW_REGISTRATION=true

# Invite-only (requires registration code or membership invitation)
AUTH_ALLOW_REGISTRATION=invite

# Closed (no self-service sign-up)
AUTH_ALLOW_REGISTRATION=false

# Let membership invitations satisfy sign-up gate
AUTH_INVITE_CODE_SIGNUP=true

Create registration codes (invite-only mode):

# Single-use email invite
nexus auth invitations create-email --email user@example.com

# Reusable registration code (10 uses)
nexus auth invitations create-code --max-uses 10

Registration codes use the format nxr_... and are hashed (BLAKE3) in the database.

User Lifecycle Management

Create a user (with optional org/project membership):

Platform administrators can create user accounts programmatically through the CLI, optionally assigning them to specific organizations and projects with designated roles during the creation process. This capability is particularly useful in closed registration environments where all accounts must be manually provisioned, or when onboarding users who need immediate access to specific resources without going through the self-service signup flow. When creating a user, administrators can specify their email address (which serves as the primary identifier), display name, initial password (passed securely through environment variables to avoid shell history exposure), and any number of workspace, organization, or project memberships with appropriate roles. This atomic operation ensures that users are fully configured and ready to work immediately upon account creation, rather than requiring separate steps to create the account and then assign permissions. The CLI also supports batch user creation through scripting, enabling integration with HR systems or automated onboarding workflows that provision Nexus access as part of broader employee lifecycle processes.

nexus auth users create \
  --email user@acme.com \
  --name "Alice Smith" \
  --password-env USER_PASSWORD \
  --org acme/engineering \
  --project ml-pipeline \
  --role manager

List users:

nexus auth users list --include-inactive
nexus auth users list --org acme/engineering

Disable a user (soft delete, blocks login):

nexus auth users disable user@acme.com

Re-enable a user:

nexus auth users enable user@acme.com

Users are stored in the nexus_auth database with session management via HTTP-only cookies and JWTs.

Provider Integrations

Nexus supports two modes for AI provider access:

BYOK (Bring Your Own Key) - Tenants supply their own provider API keys
PTB (Pass-Through Billing) - Platform supplies keys and charges tenants via wallet

Platform Keys (PTB)

Platform administrators manage provider keys for PTB-enabled workspaces. Keys are scoped hierarchically: project → org → workspace → tenant/global.

Set a platform key:

nexus credentials platform-keys set \
  --provider openai \
  --secret-env OPENAI_API_KEY \
  --workspace acme \
  --label "Production Key"

List platform keys:

nexus credentials platform-keys list --provider openai --workspace acme

Rotate a key:

nexus credentials platform-keys rotate ppk_... --secret-env NEW_OPENAI_KEY

Remove a key:

nexus credentials platform-keys rm ppk_...

Supported providers:

OpenAI, Anthropic, Gemini, Groq, Mistral, Cohere
xAI, Together, Fireworks, DeepSeek, Perplexity
Azure AI Foundry (with deployment discovery)

Azure Foundry discovery:

nexus credentials platform-keys discover ppk_... --apply

Automatically maps Azure deployments to canonical model names.

Security:

All keys encrypted with FileKMS (AES-256-GCM)
Wrapping key stored at --state-dir/control-plane.kms.key (mode 0600)
Audit events: providerkey.created, providerkey.rotated

Enable PTB routing:

NEXUS_GATEWAY_PTB=1  # Enable PTB fallback routing

See BYOK/PTB Routing for technical details.

Tenant Provider Keys (BYOK)

Tenants create their own provider keys:

nexus credentials provider-keys create \
  --org acme/engineering \
  --project ml-pipeline \
  --provider anthropic

Keys are scoped to a project and encrypted before storage.

Related documentation:

Billing and Wallets

Nexus uses workspace wallets for PTB billing with Stripe integration.

Stripe Configuration

Environment variables:

NEXUS_STRIPE_API_KEY=sk_test_...           # Server-side secret
NEXUS_STRIPE_WEBHOOK_SECRET=whsec_...      # Webhook signature verification
NEXUS_STRIPE_PUBLISHABLE_KEY=pk_test_...   # Browser-safe (served to console)
NEXUS_GATEWAY_PTB=1                         # Enable PTB routing

API endpoints:

GET /api/payments/config - Returns publishable key for console
POST /api/workspaces/:ws/wallet/topups - Create Stripe PaymentIntent
POST /api/payments/webhooks/stripe - Webhook handler (HMAC-verified)
POST /api/workspaces/:ws/wallet/refunds - Refund settled payment
GET /api/workspaces/:ws/wallet/transactions/export.csv - Ledger export

Operator Credits (PTB Funding)

Grant credits to workspaces for pilot programs or promotional purposes:

nexus ops grants create \
  --workspace ws_... \
  --amount-usd 100.00 \
  --reason "pilot credit" \
  --idempotency-key pilot-credit-001

PTB Eligibility

Enable PTB access for a workspace:

# Via REST API
PATCH /api/workspaces/:workspace_id/limits
{
  "ptb_enabled": true
}

Console UI also provides a toggle under workspace settings.

Wallet Mechanics

Database schema:

workspace_wallets - Current balance and reserved amounts
workspace_wallet_escrows - Reserved credits for in-flight requests
workspace_wallet_transactions - Immutable ledger
workspace_wallet_topups - Stripe payment tracking
workspace_billing_receipts - Settlement records

Reconciliation: The control-plane service compares Stripe settlements to wallet credits and emits wallet.reconciliation.mismatch audit events if discrepancies are found.

Spend caps: Monthly usage is rolled up in ClickHouse (usage_monthly_rollup FINAL) and checked before requests are routed.

Audit events:

wallet.topup.succeeded
wallet.refund.created
wallet.escrow.reserved
wallet.escrow.committed

See Billing Operations for detailed workflows.

System Monitoring and Health

Health Endpoints

All services expose /healthz endpoints:

Service	Port	Endpoint
Gateway	14450	`http://127.0.0.1:14450/healthz`
Console	14449	`http://127.0.0.1:14449/healthz`
Control-plane	14451	`http://127.0.0.1:14451/healthz`
Auth	14453	`http://127.0.0.1:14453/healthz`
Policy	14455	`http://policy:14455/healthz`
Ingest	14457	`http://127.0.0.1:14457/healthz`
Trace-ingest	14458	`http://127.0.0.1:14458/healthz`
Audit	14459	`http://127.0.0.1:14459/healthz`
Query	14461	`http://127.0.0.1:14461/healthz`

Check all services:

just status  # Formatted health summary

Metrics and Observability

All services expose Prometheus metrics at /metrics.

Key metrics:

vortex_service_starts_total
nexus_gateway_attempt_total{provider, result, virtual_key_id}
nexus_ingest_dlq_total{reason}

Development observability stack:

Grafana: http://127.0.0.1:14470 (dashboards)
Prometheus: Scrapes all /metrics endpoints
Tempo: Distributed tracing storage
Loki: Log aggregation
OTel Collector: http://127.0.0.1:18888/metrics

Configuration:

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

Committed dashboards:

5 Grafana dashboards in deploy/compose/grafana/dashboards/

See Ports Reference for complete port mapping and Observability for detailed monitoring setup.

Security and Compliance

Data Classification

Nexus enforces hierarchical data classification with customizable labels.

Default vocabulary:

public < internal < confidential < restricted

Set workspace classification policy:

nexus workspaces update acme \
  --classification-tiers "public,internal,confidential,restricted" \
  --default-classification internal \
  --classification-ceiling confidential

Classification header:

nexus-classification: confidential

The policy engine denies requests that exceed the configured ceiling label for the project.

Hierarchy rules:

Child scopes (org/project) inherit parent lattice
Ceilings can only be tightened (more restrictive) in child scopes

See Classification Header for technical details.

Policy Engine

The policy service evaluates every gateway request and returns allow/deny decisions with obligations.

Reason codes:

classification_ceiling_exceeded
classification_vocabulary_missing
spend_cap_exceeded
wallet_insufficient_balance

Obligations:

redact_email - Remove PII from prompts
rate_limit - Apply per-request rate caps
audit_tag - Add metadata to audit events
require_escrow - Reserve wallet funds before routing

Caching: Requires NEXUS_REDIS_URL for Redis-backed decision caching.

See Policy Obligations for the complete contract.

Tamper-Evident Audit Trail

Nexus maintains cryptographically verifiable audit logs using per-tenant Merkle chains.

Key features:

Ed25519-signed batch roots
BLAKE3 hashing with CBOR deterministic encoding
WORM (Write-Once-Read-Many) archival
Inclusion proofs for every event

Database:

audit_events - Individual events
audit_batch_roots - Signed batch Merkle roots
audit_meta_roots - Cross-tenant meta roots
audit_signing_keys - Key material

Verification:

nexus-audit-verify

API:

GET /api/audit/events - Query events (RBAC: manager/auditor only)
GET /api/audit/events/:event_id/proof - Inclusion proof

Audit event types:

gateway.request.completed
policy.decision
wallet.* (topup, refund, escrow)
user.* (created, signed_in, disabled)
org.*, project.*, providerkey.*

See Audit Event Reference for schema details.

Rate Limiting

Configuration:

NEXUS_REDIS_URL=redis://...           # Required for rate limiting
NEXUS_GATEWAY_RL_RPS=10               # Requests per second
NEXUS_GATEWAY_RL_RPM=600              # Requests per minute

Rate limits are enforced per API key. The policy engine can also apply per-request caps via obligations.

Secrets Management

Provider keys:

Encrypted with FileKMS (AES-256-GCM)
Wrapping key: --state-dir/control-plane.kms.key (mode 0600)
Audit trail: providerkey.created, providerkey.rotated

Session secrets:

AUTH_JWT_SECRET=...        # Session JWT signing key
NEXUS_SERVICE_TOKEN=...    # Internal RPC authentication

Compliance Mapping

Nexus supports compliance frameworks including NIST SP 800-53:

AU-2 (Audit production) - All control-plane and data-plane events
AU-9 (Audit protection) - Tamper-evident Merkle chains
AU-10 (Non-repudiation) - Signed batch roots
AU-11 (Retention) - Configurable archival policies
RA-5 (Vulnerability scanning) - CI/CD integration
SI-2 (Updates) - Dependency management
SR-4/SR-11 (Supply chain) - SBOM generation

See Compliance Mapping and Threat Model for complete security documentation.

Model Registry and Pricing

Platform administrators can sync provider pricing data to ensure accurate cost tracking.

Sync provider pricing:

nexus registry models sync --provider openai

Create and apply a pricing update plan:

# Create plan
nexus registry models plan --provider openai

# Review plan
nexus registry models show-plan <plan-id>

# Approve plan (1 hour validity)
nexus registry models approve-plan <plan-id> --expires-in-seconds 3600

# Apply plan (with advisory lock)
nexus registry models apply-plan <plan-id>

List models:

nexus registry models list
nexus registry models get gpt-4o