application public active Verified 2026-04-29

Topolo Nexus

Gateway and usage-management layer for standardized AI, email, payment, and org-scoped model-preference access across the Topolo platform.

Documentation Map

What It Is

Gateway and usage-management layer for standardized AI, email, payment, and org-scoped model-preference access across the Topolo platform.

Canonical documentation for Nexus lives in `PlatformApplications/TopoloDocs`.

Use this repository for implementation only. Runtime shape, API contracts, provider policy, deployment behavior, and migration status must be updated in the docs application rather than in repo-local guides.

Architecture

Owners: ai-platform

Source repos: PlatformApplications/TopoloNexus

Dependencies: topolo-auth, applications-packages

Repo shape

PlatformApplications/TopoloNexus/README.md
PlatformApplications/TopoloNexus/apps/
PlatformApplications/TopoloNexus/docs/
PlatformApplications/TopoloNexus/infra/
PlatformApplications/TopoloNexus/migration.config.ts
PlatformApplications/TopoloNexus/package-lock.json
PlatformApplications/TopoloNexus/package.json
PlatformApplications/TopoloNexus/pnpm-lock.yaml
PlatformApplications/TopoloNexus/pnpm-workspace.yaml
PlatformApplications/TopoloNexus/topolo.cloudcontrol.json

Runtime Surfaces

Hosts:

https://nexus.topolo.app https://topolo-nexus-gateway.topolo.workers.dev https://topolo-nexus-dashboard-staging.pages.dev https://topolo-nexus-gateway-staging.topolo-staging.workers.dev

topolo-nexus-dashboard

Config: PlatformApplications/TopoloNexus/apps/dashboard/wrangler.toml

Main: not declared

Routes: workers.dev or asset-only surface

topolo-nexus-gateway

Config: PlatformApplications/TopoloNexus/apps/gateway/wrangler.toml

Main: src/index.ts

Routes: workers.dev or asset-only surface

API Reference

Coverage: curated

Source: PlatformApplications/TopoloNexus/package.json

Source exists in repo: yes

Canonical docs and gateway routes define Nexus as the typed provider gateway for AI, email, payments, provider-credential resolution, reusable outbound sender identities, and org-scoped model preferences, with platform-default credential mutation restricted to Auth `platform_super_admin` principals in the `admin` organization and broader platform-scoped service-client administration accepting Auth `platform_admin` or `platform_super_admin` from that same org. Trusted service-context auth now supports a primary shared token, additional staged tokens through `TRUSTED_SERVICE_TOKENS`, and dedicated app-specific tokens such as `SUPPORT_NEXUS_SERVICE_TOKEN` when a single migrated worker needs unattended service-context delivery without rotating the shared token set. TopoloMail uses a dedicated service-client token for `/api/ai/completions` and `/api/ai/transcriptions`, with dynamic organization attribution and user delegation so mailbox AI and dictation usage are logged to the active user, organization, and app. TopoloWeb now forwards studio bearer tokens to Nexus for structured chat planning responses that are applied locally as typed site mutations, keeping Nexus responsible for provider invocation while TopoloWeb keeps blueprint validation and persistence. Supported AI routes can now also flow through authenticated Cloudflare AI Gateway from inside Nexus without changing the external `/api/ai/*` contract, with gateway transport settings kept in worker config and secrets rather than `provider_credentials` rows. The image preference surface now treats the Nexus org setting as the baseline while allowing products to request per-run inline overrides against the allowed model catalog, including OpenAI GPT Image models, without mutating the stored org preference. Stripe price creation accepts either an existing product ID or caller-supplied product data while keeping provider credentials inside Nexus, and the typed payment surface now also supports subscription quantity updates plus invoice previews for owner-managed billing flows such as TopoloOne org seats. For TopoloP2P, Nexus remains behind TopoloPay only: P2P submits settlement requests to Pay, and Pay uses the Nexus typed payment surface for provider invocation. The gateway now also exposes authenticated `GET /api/widget` for TopoloOne live workspace. The dashboard browser login handoff and one-time sso_code callback redemption delegate to the shared Topolo auth client, embedded password-login success completes through Nexus app navigation after token persistence, and the authenticated dashboard workspace renders through the shared `TopoloAppShell` so account, launcher, command, theme, sidebar-collapse, and BugFix chrome stay package-owned. Auth API-key scopes for `srv_nexus` are manifest-aligned with the Nexus permission contract and synced to production D1.

App API page: /reference/apps/topolo-nexus

This system currently relies on a curated or README-derived contract surface instead of a source-controlled OpenAPI spec.

Auth and Permissions

Depends on Topolo Auth: yes

Service IDs:

srv_nexus

API key scopes

ai.invoke

Invoke Nexus AI-provider routes through authenticated service-client contexts

Resource pattern: none

apps.read

View Nexus application and attribution metadata

Resource pattern: none

org.admin

Manage Nexus organization-scoped administrative settings

Resource pattern: none

organizations.provision

Provision organization-scoped Nexus service-client access

Resource pattern: none

provider_credentials.manage

Manage Nexus provider credentials and platform defaults

Resource pattern: none

service.invoke

Invoke Nexus service-client routes through authenticated service-client contexts

Resource pattern: none

usage.read

View Nexus usage, budget, and provider telemetry

Resource pattern: none

Service permissions

ai:invoke, apps:read, org:admin, organizations:provision, provider_credentials:manage, service:invoke, usage:read