Topolo Nexus

Public overview of Nexus as the platform gateway for metered provider and application usage across Topolo applications.

publicverified 2026-08-01aigatewayusageplatform

What It Is

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

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.

Provider connections receive stable Nexus references. Product apps keep their business objects and labels while Nexus keeps credentials, provider identifiers and status, and provider-owned verification decisions. For Meta messaging, Nexus also verifies the external webhook and signs the complete tenant, app, resource, connection, and body context delivered to the receiving product. Verification uses the encrypted, environment-specific credential for the exact target application; a webhook is not routed until one active application credential verifies it.

Nexus also keeps provider display names, avatar/profile links, scopes, expiry, and terminal lifecycle state. Trusted provider callbacks can resolve an account by provider subject through an app-bound lookup, and only an explicit OAuth reconnect can reactivate a disconnected or deauthorized connection.

Runtime Surfaces

  • Nexus gateway worker
  • Nexus dashboard
  • D1-backed usage, key, provider-credential, and preference storage
  • generic application usage ingestion for API-backed apps

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://nexus-api.topolo.app

The isolated staging mirror uses https://nexus.stg.topolo.us for the dashboard and https://nexus-api.stg.topolo.us for the gateway. Staging dashboard builds inject staging Auth, Admin, dashboard, and gateway origins so browser bundles do not drift back to production.

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
  • /api/models
  • /platform/usage/events
  • /platform/integrations/connections/*

The /api/provider-credentials surface is reserved for the platform-default credential management flow and is not a general end-user API. The image-generation preference surface returns the stored organization preference when one exists; otherwise it returns the Nexus platform image baseline, currently OpenAI GPT Image 2 (gpt-image-2) with Google Nano Banana 2 (gemini-3.1-flash-image-preview) as the managed-provider fallback. Runtime image generation follows that order and can use the on-platform Cloudflare image route as an operational safety net if managed external providers reject before returning an image. OpenAI image metering uses provider-reported GPT image usage when available and otherwise falls back to a bounded size/quality estimate rather than deriving billable output tokens from returned image payload length. The allowed image catalog includes OpenAI GPT Image 2 and Google Nano Banana model ids for product UIs that expose permission-gated per-request overrides. The model-governance surface exposes the configured platform defaults, organization overrides, recent usage by model, lifecycle status, source verification freshness, and upstream candidate models observed from provider catalogs. Nexus runs this catalog sync from the gateway Worker schedule and restricts manual refresh to platform super admins.

API Reference

Nexus currently uses curated docs coverage rather than a published OpenAPI surface in TopoloDocs. The live contract is centered on typed route families for AI completions and generations, email send operations, payment operations, generic app usage events, 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.

/platform/usage/events is the generic application usage route for API-backed apps and platform services. It records stable app, organization, optional user, meter, event, unit, and request-id attribution so Nexus reporting can show how much each user and organization consumes even when the event is not a direct provider call.

Image-generation defaults stay in Nexus and provider rate-limit responses are retryable so requests can continue through the configured AI fallback chain before a product surfaces failure. Scoped hard-stop spend limits are restricted to organization owners, organization super admins, and platform super admins. The dashboard and API use Nexus-provided option metadata for allowed app, user, capability, use-case, provider, and model values instead of accepting arbitrary scope text.

Standardization Rule

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

This rule is aimed at vendor APIs such as AI, messaging, enrichment, similar usage-billed integrations, and platform API-call metering. 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 or app-switch entry so transient auth events do not flash the user back to the login screen or public landing page. That refresh path depends on Topolo Auth allowing the X-Topolo-Auth and X-App-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-io/auth-client package. Direct bearer-token callback URLs and /sso?token= bridge routes are not supported.

The service-context path requires:

  • Authorization: Bearer <Auth service JWT>
  • X-Nexus-Organization-Id
  • X-Nexus-App-Id when the service JWT slug does not fully identify the calling app
  • optional X-Nexus-User-Id

User-driven routes should forward the caller's bearer token instead. Service workers should mint Auth service JWTs and carry organization, app, and optional user attribution in request headers. Fixed-org payment surfaces such as TopoloOne marketing checkout and TopoloPay set X-Nexus-Organization-Id to the Auth organization with slug topolo. TopoloNotify uses the same platform-sender pattern for default transactional email, including recovery-email verification, so topolo.app and stg.topolo.us sender-domain ownership stays attached to the Topolo platform organization rather than each customer organization.

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, model lifecycle metadata, upstream catalog observations, 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 Auth-issued service JWTs for backend-to-backend calls, 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, organization, request, or delegated-user 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 token or Auth service-JWT context headers are present.

Use It

Open Topolo Nexus for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-nexus --json
topolo actions --service topolo-nexus --json
topolo actions capabilities --service topolo-nexus --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

  1. Confirm the active identity and organization with topolo whoami --json.
  2. Discover Topolo Nexus and select one published action rather than guessing a route.
  3. Inspect its input/output schemas and published example.
  4. Validate and plan the exact payload; obtain confirmation for a mutation.
  5. Execute and perform every published verification step.

Change Log / Verification

  • Deployed app-bound Meta webhook credentials and the validated product-relay registration contract on staging on 2026-08-01 at source 84fe731656363b303a7d3d8f924107f9f0d1bfab, dashboard version 10c406d9-d809-4900-8ece-5be89a353d0c, and gateway version 781bd834-a555-4590-8de4-299033ff0d71. A signed staging event completed the Nexus-to-Messages relay; invalid signatures failed with HTTP 401 and unknown numbers did not cross a tenant boundary.

  • Added and staging-verified app-bound provider lookup, provider profile projection, and explicit reconnect reactivation on 2026-08-01; Socialize now consumes that contract as its sole connected-provider authority.

  • Deployed and verified the stable Meta connection-reference and context-bound relay contract on staging on 2026-08-01 at source 98670312d18757d2232e454cee827222f0a39b76 and gateway version 566bbef4-e791-44bc-89fa-85bc52a0f6f6.

  • Reconciled docs freshness on 2026-06-28 against topolo-platform through 20653c79; latest commit reviewed was 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap), with recent context 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap); 61117a0d feat(app-shell): add lazy component factory; d8784cfa feat(app-shell): add canonical lazy route factory.

  • Added generic platform usage-event coverage on 2026-06-04 so API-backed apps and platform services can report app, organization, optional user, meter, unit, and request-id attribution through Nexus instead of maintaining local counters.

  • Added model-governance and catalog-monitoring coverage on 2026-05-07 so Nexus can show configured defaults, recent model usage, lifecycle risk, source health, and newly observed upstream model candidates.

  • Restricted scoped hard limits to owner/super-admin managers on 2026-05-02 and changed the dashboard to use Nexus-provided searchable scope options.

  • Treated raw provider HTTP 429 image-generation responses as retryable on 2026-05-02 so Nexus continues through the configured AI fallback chain.

  • Recast Nexus onto the explicit platform-role model on 2026-04-24 so platform-default provider credentials require Auth platform_super_admin; backend service access now comes from Auth-issued service JWTs rather than Nexus-local service-client rows.

  • 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

  • Retired dedicated static Nexus service tokens in favor of Auth-issued service JWTs for unattended service delivery.

  • 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