Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🔗Connect a Nexus API dApp

Audience: Developers wiring an external frontend, bot, or backend to the hosted Nexus API.

Goal: Choose a relay shape that keeps the provider-issued key server-side, preserves public response diagnostics, and supports REST plus replayable SSE.

Every integration answers one question first: where does the key live? It lives in a process you control on the server side, never in a browser bundle, public environment variable, local storage, URL, or source repository. Three patterns cover the normal external consumer shapes.

Stack
Key lives in
Public browser path

Full-stack framework

Route handlers or server actions

Same-origin REST and SSE relay

Static SPA

A reviewed reverse proxy or sidecar

Same-origin REST and SSE relay

Bot or backend service

The service process

Direct server-side REST and SSE

Browser relay for hosted Nexus API

The architecture figure shows the boundary the application must preserve: the provider owns the hosted API, your server-side process owns the secret, and the browser receives only public response and event state.

The sequence keeps credential injection and cursor forwarding on the server side. REST is the view source; SSE wakes the application to re-read and recover. These examples use one explicit upstream URL contract: NEXUS_API_URL must be an origin-root https: URL with no path, query, or fragment, because the relay appends /executions and /events/stream at the origin root. If a provider publishes a path-prefixed endpoint, put a separate reviewed adapter in front of it rather than passing that path to these examples.

Pattern A — full-stack framework relay

A framework route handler can proxy only the exact resources the UI needs. This example forwards executions and the event stream, preserves status and body, and exposes a positive response-header allowlist:

The relay validates NEXUS_API_URL as an absolute https: URL before it constructs an upstream request or attaches x-api-key. This example has no plaintext loopback exception: local browser-to-relay HTTP is acceptable, but the credential-bearing upstream target must use HTTPS.

Use a separate allowlisted handler for the stream so it forwards Last-Event-ID, sets no-cache and no-transform, and disables proxy buffering. Abort the upstream fetch when the browser disconnects. Reject every path outside a fixed route set before constructing the upstream URL.

The allowlist must drop cookies, redirects, authentication challenges, CSP, site-data, upstream cache, and body-framing or encoding headers. Add application authentication, authorization, CSRF protection, and observability before exposing the relay to users.

Pattern B — SPA behind a reviewed proxy

A static SPA uses the same public paths behind a reverse proxy or sidecar. The proxy may inject x-api-key and disable SSE buffering, but transport-only configuration is not sufficient for a production cross-origin boundary: prove the positive response-header policy with a test that preserves status/body and drops unsafe headers.

Bind a local development proxy to loopback, keep NEXUS_API_KEY in the server process, and never expose it through a VITE-prefixed variable. The React tutorial uses the repository's temporary Vite fixture to typecheck, audit, and scan the real bundle.

Pattern C — direct backend service

A backend service can call the hosted API directly. Keep the key in the service secret manager, use the smallest provider-granted scopes, retry only idempotent reads, and persist event cursors after validating complete frames:

For SSE, use a parser that preserves the last numeric id and sends it as Last-Event-ID on reconnect. Re-read the affected REST resource after a frame; the stream is a replayable signal, not a second database.

Relay checklist

  • Allowlist exact paths and methods; reject dot segments, encoded slash or backslash, malformed escapes, and unknown routes before adding the key.

  • Forward the upstream status and body instead of replacing an API error with a local 502.

  • Forward only content type, request id, conditional error code, retry, and rate-limit diagnostics.

  • Set local REST no-store and SSE no-cache, no-transform plus X-Accel-Buffering no.

  • Forward the encoded last_event_id query without dropping the relay path or existing query parameters.

  • Abort authenticated upstream work when the browser disconnects.

  • Render response strings as text and validate JSON, event shape, content type, and bounded body detail before use.

  • Reconnect with the last validated event id and use bounded exponential backoff for 408, 429, and 5xx.

  • Run the consumer's relay and bundle checks before shipping, then run the public Docs lint gate.

Next

Use the HTTP API reference for public endpoint contracts, or return to the Nexus API tutorial.

Last updated