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

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.

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

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

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 the configured platform super-admin account 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 one shared trusted-service token across migrated worker runtimes, while bearer-token forwarding remains the standard for user-driven routes.

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 Nexus instead of directly to the vendor and that its bearer or trusted service-context headers are present.

Change Log / Verification

• 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