Topolo Nexus

What It Is

Topolo Nexus is the platform gateway for metered third-party API usage across Topolo applications. It centralizes provider access, usage logging, app attribution, and budget-aware routing instead of each application managing provider keys independently.

Architecture

Nexus ships as a Cloudflare-backed gateway plus dashboard. The gateway now fronts typed AI, email, and payment provider operations rather than acting as a raw passthrough proxy.

Platform-default vendor credentials are now persisted inside Nexus rather than resolved directly from product apps. Nexus worker PLATFORM_* secrets now act only as the bootstrap source for missing platform-default rows in the Nexus provider_credentials store.

Runtime Surfaces

• Nexus gateway worker
• Nexus dashboard
• D1-backed usage, key, provider-credential, and preference storage

The Nexus dashboard uses TopoloAppShell from the shared Topolo UI Kit for its authenticated workspace, including the standard sidebar, account menu, command palette, top utility controls, direct light/dark theme toggle, app launcher, BugFix reporter entrypoint, and first-party app icon treatment. Nexus preferences stay inside the dashboard, while identity/security settings hand off to Topolo Admin’s /security/user route.

Current production host split:

• dashboard origin: https://nexus.topolo.app
• gateway worker origin: https://topolo-nexus-gateway.topolo.workers.dev

API Surface

The current gateway route families are:

• /api/ai
• /api/email
• /api/payments
• /api/keys
• /api/provider-credentials
• /api/usage
• /api/preferences
• /api/apps

The /api/provider-credentials surface is reserved for the platform-default credential management flow and is not a general end-user API.

API Reference

Nexus currently uses curated docs coverage rather than a published OpenAPI surface in PlatformApplications/TopoloDocs. The live contract is centered on typed route families for AI completions and generations, email send operations, payment operations, plus usage, key, preference, and app metadata routes. Stripe price creation accepts either an existing product ID or Stripe product data supplied by the calling app.

Standardization Rule

Topolo applications should use Nexus for outbound calls to metered third-party APIs where attribution by organization, user, and application matters.

This rule is aimed at vendor APIs such as AI, messaging, enrichment, and similar usage-billed integrations. It does not automatically apply to webhook verification secrets, OAuth client secrets, or infrastructure credentials.

Current Rollout State

The current standardization slice now covers:

• Roadmapper AI generation and notification email delivery
• BugFix AI generation and validation
• Showcase generation and video-analysis flows
• Socialize text, image, trend, email, and billing flows
• Topolo Social Studio planning and generation flows
• TopoloOne checkout creation and webhook-side subscription retrieval
• TopoloPay outbound order, refund, status, and cancellation operations
• TopoloCommerce server-side voice transcription and voice-intent resolution through the Commerce worker using trusted service-context attribution

Auth and Permissions

Nexus relies on Topolo Auth bearer tokens or trusted service-to-service credentials so provider usage can be attributed to the correct organization and user context. The Auth API-key scope catalog for Nexus mirrors its permission surface across app metadata, provider-credential management, and usage telemetry. The Nexus dashboard keeps the auth surface in a loading state during initial cookie-backed session rehydration on refresh so transient auth events do not flash the user back to the login screen. That refresh path depends on Topolo Auth allowing the X-Topolo-Auth and X-Service-ID headers on the cross-origin /refresh preflight from nexus.topolo.app. The dashboard browser login handoff and one-time sso_code callback redemption delegate to the shared @topolo/auth-client package. Direct bearer-token callback URLs and /sso?token= bridge routes are not supported.

The service-context path requires:

• X-Nexus-Service-Token
• X-Nexus-Organization-Id
• optional X-Nexus-User-Id

User-driven routes should forward the caller’s bearer token instead. Fixed-org payment surfaces such as TopoloOne marketing checkout and TopoloPay set X-Nexus-Organization-Id to the Auth organization with slug topolo. Nexus can also accept dedicated per-application trusted tokens, such as the Support-specific token used for unattended notification delivery, without rotating the shared migration token set.

Credential resolution order is now:

1. organization BYOK stored in Nexus api_keys
2. Nexus-managed org override in provider_credentials
3. Nexus-managed platform default in provider_credentials

The platform-default mutation surface is restricted to Auth users whose role is platform_super_admin in the Auth admin organization. The raw secret is write-only and is never returned by the API or dashboard after save. Platform-default credentials use a fixed internal identifier per provider inside Nexus and are not user-renameable. Active platform-default credentials collapse by default in the dashboard and can be expanded when the platform admin needs to rotate or disable them.

Data Ownership

Nexus owns platform-managed provider keys, usage events, cost attribution, and provider preference routing. Product applications continue to own their own business objects and domain data.

Deployments

Nexus deploys as its own gateway and dashboard surfaces. Applications integrating with Nexus should only need Nexus connection configuration plus their normal user or service auth context, not raw vendor keys for supported integrations.

The current service-context rollout uses a primary trusted service token plus optional additional trusted service tokens for staged worker migrations, while bearer-token forwarding remains the standard for user-driven routes. Dedicated app-specific trusted tokens are also supported when a worker needs unattended delivery or retry behavior without changing the shared staged-token list.

The current bootstrap path still reads Nexus worker PLATFORM_* secrets so missing platform-default rows can be seeded into provider_credentials, but product apps should not read or hold those provider secrets themselves.

Failure Modes

• application bypasses Nexus and calls a provider directly
• provider key exists only in an app environment and not in Nexus
• missing app attribution results in incomplete usage reporting
• gateway/provider policy is not aligned with product expectations

Debugging

Start with the gateway health and usage surfaces, then confirm the application is routing outbound provider calls through the gateway worker origin instead of the dashboard origin or directly to the vendor and that its bearer or trusted service-context headers are present.

Change Log / Verification

• Recast Nexus onto the explicit platform-role model on 2026-04-24 so platform-default provider credentials require Auth platform_super_admin, while broader platform-scoped service-client administration accepts either platform role from the admin organization.
• Restored the Nexus dashboard Auth data proxy and direct shell theme toggle on 2026-04-19 so the app launcher resolves Auth /api/* service endpoints and the shell exposes light/dark mode
• Split the Nexus account menu on 2026-04-19 so Nexus preferences stay in the dashboard while identity/security settings hand off to Topolo Admin /security/user.
• Synced the Nexus Auth API-key scope catalog on 2026-04-19 so live D1 rows and generated seed SQL mirror the Nexus permission contract.
• Removed the Nexus dashboard /sso?token= browser bridge and app-local login URL construction on 2026-04-18 so login handoff and /auth/callback code redemption now rely on the shared Topolo browser auth client
• Documented dedicated app-specific trusted Nexus service tokens on 2026-04-15 so products such as Topolo Support can run unattended queued delivery without rotating the shared migration token set
• Clarified the production Nexus host split on 2026-04-12 so application integrations use the gateway worker origin for /api/* traffic instead of the dashboard origin
• Verified against the current Nexus gateway route surface, platform-key dashboard behavior, provider-credential storage model, service-token rollout, app migration state, and Auth refresh-header contract on 2026-03-31