Terminal Link is a user-friendly, hosted page designed to facilitate authentication with any telematics provider. It provides a simple, self-serve flow for customers or partners to connect their telematics accounts. You have two options to integrate Terminal Link into your application:
  1. Directly link to the hosted page.
  2. Embed it within your application using one of our SDKs.
Terminal provides a React hook that makes it easy to embed the link in your application.View the package on NPM here: @terminal-api/link-react

​
Installation

npm install @terminal-api/link-react

​
Usage

​
Creating a Connection

Terminal handles capturing, validating and securely storing customer’s credentials to ensure that each TSP integration is as consistent as possible.Here’s an overview of the steps involved when using the React hook:Steps
  1. Initialize auth link with desired options (see available options below)
  2. Open link and wait for user to complete authentication
  3. Handle onSuccess callback and exchange public token for a connection token on your backend using POST /tsp/v1/public-token/exchange

​
Re-Authenticating a Connection

In certain scenarios, connections may become disconnected. This can occur when customers modify their password or withdraw access.In such cases, Terminal updates the Connection status to disconnected and prompts you to reauthenticate the customer’s TSP to continue syncing.The reauthentication process mirrors the link flow, but requires the connectionId parameter to specify which connection needs to be updated.

​
Examples

import { useCallback } from 'react';
import { useTerminalLink } from '@terminal-api/link-react';

const MyComponent = () => {
  const api = useYourBackendApi();

  // if you are defining the function inside the component
  // make sure to wrap it in useCallback
  const exchangeToken = useCallback(
    async ({ publicToken }: { publicToken: string }) => {
      // Send the public token to your backend to exchange for a connection token
      // and store it in your database.
      return await api.post('/api/terminal', { publicToken });
    },
    [api],
  );

  const terminal = useTerminalLink({
    // production or sandbox publishable key from the Terminal dashboard
    publishableKey: process.env.REACT_APP_TERMINAL_PUBLISHABLE_KEY,
    onSuccess: exchangeToken,
    params: {
      // optional parameters
      externalId: 'my-external-id',
    },
  });

  return (
    <div>
      <button onClick={() => terminal.open()} disabled={terminal.isOpen}>
        Setup Telematics Integration
      </button>
      <button onClick={() => terminal.close()} disabled={!terminal.isOpen}>
        Close Terminal Link
      </button>
      <button onClick={() => terminal.open({ params: { provider: 'geotab' } })}>
        Setup Geotab Integration
      </button>
      <button onClick={() => terminal.open({ params: { externalId: '1234' } })}>
        Setup Integration with Custom Parameters
      </button>
    </div>
  );
};

export default MyComponent;

​
Available Options

The link SDK provides a number of options to customize the behavior of the link.Can either provide a publishableKey or url to configure the link.
​
publishableKey
string
required
Your publishable key.
​
connectionId
string
Optional connection ID to update. If not provided, a new connection will be created.
​
linkBaseUrl
string
Base URL for the link. Defaults based on the publishable key (production or sandbox).
​
url
string
Can also provide a configured link URL directly.
​
onSuccess
(data: { publicToken: string }) => void
Called when link is successfully completed.
​
params
Link Parameters