Journey URL

How to obtain and load a journey URL in your iOS app.

This guide explains where the journey URL comes from, how to obtain it, and what your iOS app needs to do with it.

Overview

The journey URL is the web address that BridgeWebView loads 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 iOS app never calls the Core SDK directly. Session creation happens server-side, and the app receives the URL through whatever API your backend exposes.

Core SDK setup

Installation

npm install @gbg/go-core

Authentication

The Core SDK authenticates with a customer access token (Bearer). Generate one using the SDK’s token endpoint:

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

const go = new Go();

const auth = await go.tokens.generate({
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
  username: "[e-mail]",
  password: "your-password",
  grantType: "password",
});

// auth.accessToken is a Bearer token for subsequent calls

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 appropriate region for your deployment using serverIdx, or provide a custom serverURL.

Create a journey session

Journey URL generation is a two-step process.

Step 1: Start the journey

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:

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

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

Pre-populate context (optional)

You can pass identity data, documents, biometrics, and consent records in the context field. This pre-populates the journey so the end user doesn’t have to re-enter information you already have:

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",
  },
},

Step 2: Get a connect token

For native app integrations, generate a connect token that the device uses for authentication:

const device = await go.devices.add({
  instanceId: journey.instanceId,
  scope: ["mobile"],
});

Response:

{
  connectToken: "s4FUx8Ny8ijXRtFigz3x1_8rb9bd_5ZD",
  tokenType: "connect",
  expiresIn: 120,    // seconds
  scope: ["mobile"],
}

The connectToken is short-lived (typically 120 seconds). Your backend should return it to the iOS app immediately after generating it.

Construct the URL

How you get the final URL to load in BridgeWebView depends on your integration pattern:

• If the instanceUrl is present in the Step 1 response, use it directly.
• Otherwise, your backend constructs the URL from the instanceId and connectToken according to your deployment’s URL scheme.

In either case, your backend returns the URL to the iOS app through your own API.

Load the URL in iOS

Once the iOS app has the URL from your backend, pass it to BridgeWebView:

struct JourneyView: View {
    @StateObject private var host = BridgeHost(hostVersion: "1.0.0")
    let journeyURL: URL  // Received from your backend

    var body: some View {
        BridgeWebView(url: journeyURL, host: host)
            .onAppear { setupHandlers() }
    }
}

The bridge handles everything else — bootstrap script injection, message handler registration, and capability negotiation all happen automatically when the page loads.

Complete backend example

A minimal Express endpoint that creates a journey session and returns the URL:

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

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

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

  // Step 1: Start journey
  const journey = await go.journeys.start({
    resourceId: req.body.resourceId ?? "a4c68509c24789888eb466@latest",
    context: {
      subject: {
        identity: req.body.identity,
      },
    },
  });

  // Step 2: Get connect token for the mobile device
  const device = await go.devices.add({
    instanceId: journey.instanceId,
    scope: ["mobile"],
  });

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

And the corresponding iOS call:

func startJourney() async throws -> URL {
    var request = URLRequest(url: URL(string: "https://your-backend.com/api/journey/start")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = try JSONEncoder().encode(["resourceId": "a4c68509c24789888eb466@latest"])

    let (data, _) = try await URLSession.shared.data(for: request)
    let response = try JSONDecoder().decode(JourneyStartResponse.self, from: data)
    return response.journeyUrl
}

Security considerations

• Never embed the customer access token in the iOS app. It is a server-side secret. The iOS app only ever sees the journey URL (and optionally the connect token).
• Always use HTTPS in production.
• Connect tokens are short-lived (typically 120 seconds) and single-use. Don’t cache or persist them.
• The journey URL should be treated as sensitive — don’t log it or store it beyond the current session.
• Fetch the URL over an authenticated channel between your app and your backend (e.g., behind your own auth middleware).

Next steps

• Integration Checklist — End-to-end setup walkthrough
• Embedding Guide — SwiftUI and UIKit patterns for displaying the journey
• Stub Camera Views — Get a working capture flow without SmartCapture SDKs