Link Component

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.

Terminal provides a javascript SDK that makes it easy to embed the link in your application.

View the package on NPM here: @terminal-api/link-sdk

​

Installation

NPM

npm install @terminal-api/link-sdk

Script Tag

<script src="https://cdn.withterminal.com/js/link-sdk.min.js" />

​

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 JS SDK:

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 if using package or will be globally available if installed via script tag
import { TerminalLink } from '@terminal-api/link-sdk';

async function exchangePublicToken(publicToken) {
  // provide the public token to your backend to exchange for a Terminal connection token
  // store the Terminal connection token in your database to use for future Terminal API requests
  const response = await fetch('/api/create-terminal-connection', {
    method: 'POST',
    body: JSON.stringify({ publicToken }),
  });

  return response.json();
}

const link = TerminalLink.initialize({
  // production or sandbox publishable key from the Terminal dashboard
  publishableKey: process.env.TERMINAL_PUBLISHABLE_KEY,
  onSuccess: (result) => exchangePublicToken(result.publicToken),
});

link.open();

​

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.

The easiest way to get started with Terminal is to redirect your users to our hosted link. This is a great option if you don’t want to embed the link in your application or if you are using a language that we don’t have an SDK for.

We will handle the entire authentication flow and redirect the user back to your application when they are done.

​

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 in that flow.

Steps

1. Create auth link with desired options (see available options below)
2. Ask user to login to their TSP and direct to link
3. User is redirected back to the redirect_url with the following paramaters:
   • result: Indicates the outcome of the authentication process. It will be either:
     • success: The user successfully authenticated.
     • exit: The user exited the authentication process without completing it.
   • token: A public token that is provided when result === success. This token is used to exchange for a connection token on your backend.
   • state: An opaque value that you can set in the link params for additional security:
     • If provided in the initial request, it will be returned unchanged.
     • You should compare the returned state with the one you initially set.
     • If they don’t match, it may indicate a potential security issue (e.g., a CSRF attack), and you should abort the authentication process.
4. Pass public token to your backend and exchange public token for a connection token
5. Wait for initial sync to complete by either:
   • Polling /connections/current until sync is complete
   • Subscribing to sync.complete webhooks (docs)
6. Ingest data from Terminal

Example Link Here’s an example of a Link URL for authenticating new connections:

https://link.sandbox.withterminal.com/?key={PUBLISHABLE_KEY}&redirect_url={URL}

​

Re-Authenticating a Connection

There are rare times where connections may get disconnected. Common reasons for this include when customers change their password or revoke access.

When this happens - Terminal will update the status of the Connection to disconnected and prompt you to reauthenticate the customer’s TSP in order to resume syncing.

Reauthentication is similar to the link flow but includes the connectionId in the URL path to denote which connection you would like to update.

Steps

1. Get re-auth link for disconnected connection (see example below)
2. Explain to user they need to enter their credentials again and direct them to link to perform authentication
3. Resume ingesting data after catch up sync completes

Example Link Here’s an example of a Link URL for re-authenticating existing connections:

https://link.sandbox.withterminal.com/connection/conn_01GSKTHCD24NRZ2SBJTPZBCQ1R?key={PUBLISHABLE_KEY}&redirect_url={URL}

​

Available Options

You can use the following options when directing customers to the link in order to control behaviour. Please note these settings do not apply to the re-authentication flow.

​

Base URL

The base URL for the link is determined by the environment you are using. You can use the following table to determine which environment you should use.

Our SDKs automatically determine the correct base URL based on the publishable key you provide.

​

Query Parameters

The following options can be appended as query parameters to the link URL in order to modify the settings of the resulting connection.