Add Path Planning to Your Platform

Overview

Each tier works on its own. Most partners start at Tier 1 (One-Click Launch) and add higher tiers later as their needs change. The sections below describe what your end-users experience, what you get as a business, the full breakdown of all four tiers, and a deep dive on Tier 1. The Technical Detail section further down contains the engineering specification.

What Your Users Experience

In Tier 1, Launch Pad acts as a companion app to your product. It opens in a new browser window with all setup handled in the background, so the user can start work immediately.

What You Get as a Partner

Built for businesses and engineering teams that want to embed precision routing without standing up the infrastructure to support it.

Four Integration Tiers

Each tier works on its own. Most partners start at Tier 1 and add higher tiers later as their needs change.

How Tier 1 Removes Friction

Why Tier 1 Exists

Account Model

A Tier 1 engagement is organized like this:

What Users See in Launch Pad

When a user opens Launch Pad through Tier 1, some Launch Pad options do not apply and are hidden:

• No password change, no email or account management, no sign-up. The user has no Launch Pad password; sign-in comes from your product. The change-password screen shows a "Password managed by [Partner]" message, the same way Launch Pad already handles users who sign in through John Deere, Trimble, or CNH.
• No company switcher. The session is locked to a single customer org for that visit.
• Logout is replaced by "Return to [Partner]", which closes the tab or sends the user back to a URL you provide, instead of leaving them on the Launch Pad sign-in page.

The main workflow menu (Plans, Path Planning, Equipment, Compare) stays available because users need it to do the work. Only identity, billing, admin, and account-management options are hidden.

Returning a Path Plan

Once a user finishes a path plan in Launch Pad, the result needs to get back into your product. Four options are available, and they work on top of any tier. Push options are strongly preferred over polling.

End-to-End Flow

What happens, step by step, when a partner user opens Launch Pad:

sequenceDiagram
    autonumber
    participant YU as Partner UI
    participant YB as Partner backend
    participant LA as Launch Pad API
    participant LU as Launch Pad UI

    YU->>YB: user clicks "Open Path Plan"

    note over YB,LA: Step 1: create LP user if not exists
    YB->>LA: POST /api/users (idempotent on externalUserId)
    YB->>LA: POST /api/company-accesses (idempotent on user + org)

    note over YB,LA: Step 2 (optional): push a boundary
    YB->>LA: POST /api/vBoundary/upsert

    note over YB,LA: Step 3: request a launch code
    YB->>LA: POST /api/partner/launch ({ userId, companyId, returnUrl })
    LA-->>YB: { code, expiresInSec: 600 }

    YB-->>YU: 302 redirect to https://your-app.vergeag.com/launch?code=...
    YU->>LU: browser navigates to /launch?code=...
    LU->>LA: POST /api/partner/launch/{code}/exchange
    LA-->>LU: JWT + refresh token
    note over LU: store JWT in localStorage,
strip code from URL,
navigate to returnUrl
          

Key Properties

• You authenticate server-to-server with a long-lived credential (the API key on your admin user). The browser never sees the API key.
• The browser only sees a short-lived, single-use, opaque code in the URL (10-minute time-to-live, consumed when exchanged).
• The exchange endpoint requires no login; the code itself is the credential. Launch Pad's UI calls it as soon as the user lands.
• Launch Pad issues a normal user session (JWT + refresh token), stores it in localStorage, and routes the user to the URL you specified.

Standards Alignment

What the Redirect URL Looks Like

What the user's browser receives (one line, as a Location: header):

https://your-app.vergeag.com/launch?code=lc_R3w9q-Kx7VtNm2bH8sLpYj4eQ6gZc1aXfU0dT5nMoP&returnUrl=%2Fpath-planning%2Fboundary%2Fb3f47e1c-8a02-4d59-9c6e-2f7a8b1d6e09

Decoded for readability:

What Launch Pad's UI Does on Landing

You do not implement this; it is included for reference so you can reason about what your users see between the click and the rendered field:

1. Reads code and returnUrl from the query string.
2. Exchanges the code with Launch Pad for a user session.
3. Signs the user in to the correct customer org.
4. Removes the code from the address bar so it doesn't linger in browser history.
5. Sends the user to the returnUrl you specified.

If code is missing, expired, or already used, the user lands on an error page that asks them to return to your product and try again.

Return-Path Options in Detail

Higher Tiers

This page is the full reference for Tier 1. For higher tiers: