Journey URL - GBG Documentation

This guide explains where the journey URL comes from, how to obtain it server-side, and how to hand it off to the host page. The credentials needed to mint a journey URL must never reach the browser. This page walks through the backend pattern that keeps them server-side.

Overview

The journey URL is the address your host page loads inside the iframe to start an identity verification flow. It is not hardcoded — your backend generates it at runtime using the GBG Go Core SDK (@gbg/go-core). The browser never calls the Core SDK. Session creation happens server-side; the host page receives the URL through your own API.

Why server-side only

@gbg/go-core’s authentication flow uses a customer access token that requires a client ID + client secret to mint. Per the Core Web Bridge SDK spec, exposing those credentials in browser code lets anyone mint sessions against your tenant. The host page must only ever see the journey URL — never the credentials, never the API responses that contain them. This rules out three otherwise-tempting patterns:

Don’t npm install @gbg/go-core in your frontend bundle. The bundle ships to every visitor — including the secret if you embed it.
Don’t proxy /api/go/* through to GBG with the secret attached. That just relocates the leak; the secret is still callable from the browser.
Don’t hand the customer access token (post-OAuth) to the browser either. It’s also a server-side secret with full tenant authority.

The only thing the browser sees is the journey URL — a short-lived, single-use, signed URL that authorizes exactly one journey instance.

Core SDK setup (backend)

The steps below run on your backend — Node.js, Bun, or Deno. Install the Core SDK, authenticate once, and reuse the resulting client for every journey session your app mints.

Installation

npm install @gbg/go-core

Authentication

Generate a customer access token using your client credentials. Do this once on backend startup, or per-request — @gbg/go-core handles token caching internally.

import { Go } from "@gbg/go-core";

const go = new Go();

const auth = await go.tokens.generate({
  clientId: process.env.GO_CLIENT_ID!,
  clientSecret: process.env.GO_CLIENT_SECRET!,
  username: process.env.GO_API_USERNAME!,
  password: process.env.GO_API_PASSWORD!,
  grantType: "password",
});

Then initialize the SDK with the token:

const go = new Go({
  customerAccess: auth.accessToken,
  serverIdx: 0, // 0 = EU, 1 = US, 2 = AU
});

Regional servers

Index	Region	Server
0	EU	`https://eu.platform.go.gbgplc.com/v2/captain`
1	US	`https://us.platform.go.gbgplc.com/v2/captain`
2	AU	`https://au.platform.go.gbgplc.com/v2/captain`

Select the region matching your deployment using serverIdx, or provide a custom serverURL.

Create a journey session (backend)

Call go.journeys.start() with a resource ID that identifies which journey template to run:

const journey = await go.journeys.start({
  resourceId: "a4c68509c24789888eb466@latest",
  context: {
    subject: {
      identity: {
        firstName: "John",
        lastNames: ["Doe"],
        dateOfBirth: "1990-01-01",
      },
    },
  },
});

Response shape:

{
  instanceId: "PiIuACmx8Q8R7qPnAkLAqBAT",  // Unique journey instance (16–64 chars)
  instanceUrl?: "https://..."                // Journey URL (present in most responses)
}

The resourceId uses the format <id>@<version> — use @latest to always run the current published version of the template.

Pre-populating context (optional)

You can pre-populate identity, documents, biometrics, and consent records via the context field. This skips data-entry steps the journey would otherwise present:

context: {
  subject: {
    identity: {
      firstName: "John",
      middleNames: ["Robert"],
      lastNames: ["Doe"],
      dateOfBirth: "1990-01-01",
      // ... additional fields as needed
    },
    documents: [],   // Pre-captured document data
    biometrics: [],  // Pre-captured biometric data
    consent: [],     // Consent records
    uid: "your-internal-user-id",
  },
}

Treat anything in context as data your backend has already collected and validated. Don’t expose this shape to your frontend without your own authentication and validation in front of it.

Advanced: device tokens

@gbg/go-core also exposes go.devices.add({ instanceId, scope }) for integrations that need a separate connect token per device — typically for native mobile apps that authenticate the device against the journey instance. For most web iframe integrations, you don’t need this — the instanceUrl from journeys.start already carries the authorization the iframe needs. If your use case requires device-level token issuance (multi-device session handoff, server-rendered handoff with subsequent device authentication, etc.), refer to the @gbg/go-core documentation for the appropriate device scope. Adding a device the iframe doesn’t need adds friction without benefit.

Return the URL to the browser

Your backend exposes an endpoint that returns the journey URL. Authenticate this endpoint with your own session/auth middleware — anyone who can call it can mint a journey on your tenant’s quota.

import { Go } from "@gbg/go-core";
import express from "express";

const app = express();
app.use(express.json());

app.post("/api/journey/start", requireUserAuth, async (req, res) => {
  const go = new Go({
    customerAccess: process.env.GO_CUSTOMER_ACCESS!,
    serverIdx: 0,
  });

  const journey = await go.journeys.start({
    resourceId: req.body.resourceId ?? "a4c68509c24789888eb466@latest",
    context: {
      subject: {
        identity: req.body.identity, // validate before passing through
        uid: req.user.id,            // tie journey to authenticated user
      },
    },
  });

  res.json({
    journeyUrl: journey.instanceUrl,
    instanceId: journey.instanceId,
  });
});

The requireUserAuth middleware is your own — it should verify the user’s session, rate-limit, and validate the request body. Without it, the endpoint becomes a free journey-minter for anyone who finds the URL.

Load the URL in the host page

Once your frontend has the URL, pass it to BridgeHostProvider:

import { BridgeHostProvider } from "@gbg/go-bridge-web-react";
import { useState, useEffect } from "react";

export function StartJourneyButton() {
  const [journeyUrl, setJourneyUrl] = useState<string | null>(null);
  const [iframe, setIframe] = useState<HTMLIFrameElement | null>(null);

  async function start() {
    const res = await fetch("/api/journey/start", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      credentials: "include",
      body: JSON.stringify({}),
    });
    const data = await res.json();
    setJourneyUrl(data.journeyUrl);
  }

  if (!journeyUrl) {
    return <button onClick={start}>Start identity verification</button>;
  }

  return (
    <BridgeHostProvider
      iframe={iframe}
      allowedOrigins={[new URL(journeyUrl).origin]}
      hostVersion="1.0.0"
      capabilities={{
        "camera.document": { supported: true, version: "1.0" },
      }}
    >
      <iframe ref={setIframe} src={journeyUrl} allow="camera" />
    </BridgeHostProvider>
  );
}

new URL(journeyUrl).origin builds the allowedOrigins entry dynamically — useful when the journey origin varies by region or tenant. Audit this if journeyUrl could ever be set from user-controlled input.

Server-side rendering (Next.js)

In Next.js App Router, fetch the URL in a server component and pass it down to a client component:

// app/journey/page.tsx (server)
import { Go } from "@gbg/go-core";
import { JourneyClient } from "./JourneyClient";

export default async function Page() {
  const go = new Go({
    customerAccess: process.env.GO_CUSTOMER_ACCESS!,
    serverIdx: 0,
  });

  const journey = await go.journeys.start({
    resourceId: "a4c68509c24789888eb466@latest",
    context: { subject: { identity: { /* ... */ } } },
  });

  return <JourneyClient journeyUrl={journey.instanceUrl!} />;
}

// app/journey/JourneyClient.tsx (client)
"use client";

import { BridgeHostProvider } from "@gbg/go-bridge-web-react";
import { useState } from "react";

export function JourneyClient({ journeyUrl }: { journeyUrl: string }) {
  const [iframe, setIframe] = useState<HTMLIFrameElement | null>(null);
  return (
    <BridgeHostProvider
      iframe={iframe}
      allowedOrigins={[new URL(journeyUrl).origin]}
      hostVersion="1.0.0"
      capabilities={{ "camera.document": { supported: true, version: "1.0" } }}
    >
      <iframe ref={setIframe} src={journeyUrl} allow="camera" />
    </BridgeHostProvider>
  );
}

The Core SDK never reaches the client bundle because it’s only imported by the server component. Verify this by checking your bundle for @gbg/go-core — if it appears, you’ve imported it from a client component by mistake.

Security considerations

Never embed @gbg/go-core credentials in browser code. Client secret, customer access token, and API username/password are all server-side secrets.
Always use HTTPS in production. The journey URL is sensitive; transport it over TLS.
The journey URL is short-lived and single-use. Don’t cache it in localStorage, don’t pass it through query strings that get logged, and don’t share it across users.
Authenticate the endpoint that returns the URL. Without your own auth in front, anyone can mint journeys on your quota.
Validate context before passing it to @gbg/go-core. Treat client-supplied identity data as untrusted — schema-validate and sanity-check before forwarding.
Audit allowedOrigins construction. If you build it from new URL(journeyUrl).origin, ensure journeyUrl itself comes from a trusted source — never from user input.

See Security → Token Exchange and Credential Safety for the full hardening pass.

Next steps

Integration Checklist — End-to-end setup walkthrough.
Embedding — React, framework-agnostic, and SSR patterns.
Security — Origin allowlist, CSP, transport, and full security model.

​Overview

​Why server-side only

​Core SDK setup (backend)

​Installation

​Authentication

​Regional servers

​Create a journey session (backend)

​Pre-populating context (optional)

​Advanced: device tokens

​Return the URL to the browser

​Load the URL in the host page

​Server-side rendering (Next.js)

​Security considerations

​Next steps