Build a browser app with user sessions

A browser session cookie belongs to the host that set it. If your application loads at https://portal.example but sends sign-in to https://dapi.example, the browser stores the cookie for dapi.example; requests rendered by portal.example cannot send it. The sign-in response can be successful while the next page load sees no session and returns to the login page.

Keep the Platform API behind your application's own origin. The browser calls /api on the app host, and your server forwards that path to the private Platform API URL. The SDK supplies the proxy so every app applies the same cookie, header, origin, stream, and failure rules.

Mount the proxyCopy Anchor Link

Install the SDK and export a handler from a server route. This TanStack Start example accepts the methods a Platform API route can receive:

import { createFileRoute } from "@tanstack/react-router";
import { createDalpProxy } from "@settlemint/dalp-sdk/server-proxy";

const proxy = createDalpProxy({
  upstream: process.env.DAPI_INTERNAL_URL!,
  origin: process.env.INVESTOR_PORTAL_URL,
  trustedProxyProfile: (() => {
    const profile = process.env.TRUSTED_PROXY_PROFILE?.trim();
    return profile === "envoy" || profile === "nginx" || profile === "openshift" ? profile : "none";
  })(),
});

export const Route = createFileRoute("/api/$")({
  server: {
    handlers: {
      GET: ({ request }) => proxy(request),
      HEAD: ({ request }) => proxy(request),
      POST: ({ request }) => proxy(request),
      PUT: ({ request }) => proxy(request),
      PATCH: ({ request }) => proxy(request),
      DELETE: ({ request }) => proxy(request),
      OPTIONS: ({ request }) => proxy(request),
    },
  },
});

The returned function is a standard (request: Request) => Promise<Response> handler. In a Node or Bun route, pass the incoming Fetch Request directly to it and return its Response. Mount /dalp through the same handler if your app serves Platform API assets such as organisation logos.

In the browser, construct the SDK client against the current origin:

import { createDalpClient } from "@settlemint/dalp-sdk";

const dalp = createDalpClient({
  baseUrl: window.location.origin,
  runtime: "browser",
});

Do not set a public DAPI URL in the browser. Keep DAPI_INTERNAL_URL server-only; it is the address the app server uses to reach the Platform API inside your network.

What the handler forwardsCopy Anchor Link

• It forwards the request method, path, query, body, cookies, auth-surface header, and Set-Cookie response headers. Cookies therefore land on the app host.
• It streams text/event-stream and application/x-ndjson responses, while buffering ordinary responses and preserving redirects and no-content status semantics.
• It removes hop-by-hop headers, host, content-length, and every client-forwarding header before the upstream request.
• It restores only the client address vouched for by trustedProxyProfile: Envoy's valid x-envoy-external-address, or the terminal valid x-forwarded-for hop for NGINX and OpenShift. none drops all of them.
• When the incoming request has no Origin, it stamps the configured public origin. An incoming origin is preserved for the Platform API's auth-surface checks.
• A failed upstream request returns 502 UPSTREAM_UNAVAILABLE; safe GET and HEAD requests retry once after a connection reset. Writes are never replayed.

Set TRUSTED_PROXY_PROFILE to match the edge that overwrites forwarding headers. An unknown or missing value is treated as none. Never trust a browser-supplied forwarding header by passing a profile that your ingress does not actually enforce.

Deployment noteCopy Anchor Link

When the Console and Investor portal run on separate hosts, each host serves its own /api and /dalp paths and forwards to the same private DAPI_INTERNAL_URL. The browser never needs a public Platform API URL. Configure the public host in INVESTOR_PORTAL_URL (or the Console's public URL setting), and keep DAPI_INTERNAL_URL as the in-cluster service address. See same-origin app deployment for Helm and OpenShift examples.

Troubleshooting: sign-in succeeds but returns to the login pageCopy Anchor Link

Inspect the sign-in response and the next session request. If the response sets a cookie for the Platform API host while the page is on your application host, the browser is doing the correct host-only cookie isolation. Mount createDalpProxy at /api, set the browser SDK baseUrl to window.location.origin, and remove the public DAPI_URL from the app. Then sign in again so the cookie is issued by the application host.