Topolo Nexus

Documentation Map

• Application hub
• Application API surface
• Machine system JSON
• Machine application JSON
• applications/nexus

What It Is

Gateway and usage-management layer for standardized AI, email, payment, social-provider app credential and connection inventory, org-scoped model-preference access, and platform model lifecycle monitoring across Topolo.

API Reference

Coverage: curated

Source: PlatformApplications/TopoloNexus/package.json

Source exists in repo: no

Canonical docs and gateway routes define Nexus as the typed provider gateway for AI, email, payments, YouTube Data API quota-unit metering, provider-credential resolution, reusable outbound sender identities, org-scoped model preferences, platform model lifecycle monitoring, and owner/super-admin scoped hard-limit option metadata, 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. Nexus email sender-domain inventory includes `cloudflare_email` connections and Topolo-owned platform sender domains so Notify can deliver default transactional email without requiring each customer organization to register `topolo.app` or `stg.topolo.us`. `GET /api/models/governance` exposes platform defaults, org or platform-scoped overrides, recent usage by model, lifecycle/deprecation status, unpriced configured models, upstream candidate models, and catalog source health; `POST /api/models/sync` is platform-super-admin only and refreshes provider API/open catalog observations. Scoped spend now includes a platform scope (`scope_type = 'platform', scope_value = 'platform'`) for spend preflight and enforcement across all provider families so a global platform budget can cap AI and platform infrastructure spend (for example, Cloudflare, Stripe, and email metering routes) while still honoring org/app-level controls. 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, and raw provider HTTP 429 image-generation responses are retryable so requests continue through the configured AI fallback chain. 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. Staging dashboard builds inject staging Auth, Admin, dashboard, and gateway URLs, and the staging gateway is cataloged on `https://nexus-api.stg.topolo.us` with workers.dev only as a fallback route. Auth API-key scopes for the `topolo-nexus` service slug 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:

API key scopes

Service permissions

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

Data Ownership

No storage bindings were derived from wrangler configuration.

Deployments

Deployment environments: default only or not declared

Routes: workers.dev or Pages-only delivery

Observability enabled: no explicit setting found

Failure Modes

• No wrangler.toml surface was discovered under the registered repo paths.
• The registered contract source is missing: PlatformApplications/TopoloNexus/package.json
• Neither OpenAPI nor README-derived interface detail was found.

Debugging Runbooks

Start with these entrypoints:

• PlatformApplications/TopoloNexus/package.json

Change Log / Verification

Lifecycle: active

Last verified: 2026-05-19

Any code change to this system is expected to update the canonical docs in PlatformApplications/TopoloDocs and refresh the verification date.