Tied-agent walkthrough (Next.js + BFF)

Build a Next.js app that embeds Assetera's catalog for your customers, as a tied-agent tenant. Your app ships a thin Backend-for-Frontend (BFF): a server layer, under your control, that holds all tokens and calls Assetera on the browser's behalf.

One rule above all: the browser never receives a general Assetera API access or refresh token. Those tokens live server-side; the browser holds only an opaque, HttpOnly session cookie. Purpose-restricted, short-lived SDK and wallet tokens are the explicit exceptions described below.

Under a tied-agent arrangement, Assetera runs KYC/AML and you operate under its licence. See Tenancy & responsibility for reliance vs tied agent, and Authentication for the OIDC grants and token contract (this page links to it rather than re-explaining it).

The complete tied-agent flow

Before you integrate, your organization signs up with Assetera. Assetera provisions a tenant-scoped OIDC client, MetaKYC SDK credentials, allowed redirect origins, and the wallet configuration enabled for your environment. These are organization credentials, not end-user credentials.

The Keycloak sub is the join key. Do not create a separate random KYC user ID or wallet user ID. Use the signed-in customer's sub as MetaKYC's externalRefId; the embedded wallet receives the same subject through an audience-restricted token exchange.

Runtime shape

For ordinary Marketplace API calls there are three parties: the browser, your BFF, and Assetera Identity plus the Marketplace API. The browser talks to your BFF and does not receive the Marketplace API token. The onboarding SDK and embedded wallet use their own restricted browser-token boundaries, as shown in the complete flow above.

The example project

A minimal App Router layout: a page, three auth route handlers, one catch-all proxy, and two lib modules.

Walkthrough

// lib/oidc.ts
import * as client from "openid-client";

// e.g. https://auth.<base_domain>/realms/assetera
const issuerUrl = new URL(process.env.ASSETERA_ISSUER!);

export async function getConfig() {
  return client.discovery(issuerUrl, process.env.ASSETERA_CLIENT_ID!, {
    client_secret: process.env.ASSETERA_CLIENT_SECRET!,
  });
}

const response = await fetch("/api/kyc/status", { cache: "no-store" });
const status = await response.json();
if (!status.verified) {
  // redirect to KYC, or hide trade controls
}

Route handlers

// app/api/auth/login/route.ts
import * as client from "openid-client";
import { getConfig } from "@/lib/oidc";
import { getSession } from "@/lib/session";

export async function GET() {
  const config = await getConfig();
  const verifier = client.randomPKCECodeVerifier();
  const challenge = await client.calculatePKCECodeChallenge(verifier);

  const session = await getSession();
  session.pkceVerifier = verifier;
  await session.save();

  const url = client.buildAuthorizationUrl(config, {
    redirect_uri: process.env.ASSETERA_REDIRECT_URI!,
    scope: "openid profile marketplace",
    code_challenge: challenge,
    code_challenge_method: "S256",
  });

  return Response.redirect(url.href);
}

// app/api/auth/callback/route.ts
import * as client from "openid-client";
import { getConfig } from "@/lib/oidc";
import { getSession } from "@/lib/session";

export async function GET(req: Request) {
  const config = await getConfig();
  const session = await getSession();

  const tokens = await client.authorizationCodeGrant(config, new URL(req.url), {
    pkceCodeVerifier: session.pkceVerifier!,
  });

  // Tokens live server-side only. Browser gets nothing but the cookie.
  session.accessToken = tokens.access_token;
  session.refreshToken = tokens.refresh_token;
  session.pkceVerifier = undefined;
  await session.save();

  return Response.redirect(new URL("/", req.url).href);
}

// app/api/[...proxy]/route.ts
import { getSession } from "@/lib/session";

const API_BASE = process.env.ASSETERA_API_BASE!; // no hardcoded host

async function handle(req: Request, { params }: { params: { proxy: string[] } }) {
  const session = await getSession();
  if (!session.accessToken) return new Response("unauthenticated", { status: 401 });

  const upstream = `${API_BASE}/${params.proxy.join("/")}`;
  return fetch(upstream, {
    method: req.method,
    headers: {
      authorization: `Bearer ${session.accessToken}`, // attached server-side
      "content-type": req.headers.get("content-type") ?? "application/json",
    },
    body: req.method === "GET" ? undefined : await req.text(),
  });
}

export { handle as GET, handle as POST };

Rules that keep it safe

• No general API token in the browser. No Marketplace or Compliance API access/refresh token in localStorage, query strings, or non-HttpOnly cookies. The app cookie is opaque and HttpOnly, Secure, SameSite. The MetaKYC and wallet tokens are short-lived, audience-restricted exceptions and must not be reused as API bearer tokens.
• Authorization is the API's job. Your UI may hide or show controls for UX, but the Marketplace API and Assetera Identity enforce the real rules, re-checked on every call. Never move authorization into the browser.
• Tenant comes from the token, not the request. You cannot select or spoof a tenant on the wire; you get the tenant your client was issued for. (See Tenancy.)

Backend-only integration (no user browser)

If you have no interactive frontend (a server syncing catalog or acting on behalf of your book), skip the BFF and use the Client Credentials grant: your backend authenticates as its own service client, receives a token carrying your tenant claim, and calls the API directly. No user session, no cookie. See Authentication.