Terminal’s authentication system uses a two-layer approach to secure access to data:
  • API Keys identify and authenticate your application with Terminal’s platform.
  • Tokens authenticate your access to specific customer accounts.
This layered security model ensures both proper application authentication and granular customer data access controls.

​
API Keys

API keys identify your application and authenticate your requests to Terminal’s platform. Terminal provides two types of API keys for different use cases. Get your keys from the Dashboard.

​
Publishable Key

Your publishable key is used for client-side authentication from web browsers and mobile applications through the consent flow. Characteristics:
  • Safe to expose in client-side code
  • Used for browser-based integrations
  • Can only create and re-connect connections
Usage: 
import { useTerminalLink } from '@terminal-api/link-react';

const MyComponent = () => {
  const terminal = useTerminalLink({
    publishableKey: 'pk_prod_...', // Your publishable key
    onSuccess: async ({ publicToken }) => {
      // Exchange public token for connection token
      await api.post('/api/terminal', { publicToken });
    },
  });

  return (
    <button onClick={() => terminal.open()}>
      Setup Telematics Integration
    </button>
  );
};

​
Secret Keys

Secret keys are used for server-side authentication and provide full access to Terminal’s backend APIs.
Secret keys should never be exposed in client-side code or shared publicly as they grant access to all of your data and your customers’ information.
Characteristics:
  • Must be kept secure on your servers
  • Provide full API access
  • Used for backend integrations and sensitive operations
Usage: 
# Include as Authorization header in API requests
curl -H "Authorization: Bearer sk_prod_..." \
  https://api.withterminal.com/tsp/v1/connections

​
Tokens

Tokens represent your access to connected accounts, enabling you to retrieve data from specific customer telematics systems after they’ve granted consent through Terminal.

​
Connection Tokens

Connection tokens identify which specific customer connection you’re making requests on behalf of. These tokens are generated during the consent flow.
Note: Connection tokens do not expire unless rotation is explicitly requested. When a connection is disconnected and reconnected, the same token is retained.
Characteristics:
  • Specify which customer’s data to access
  • Provide connection-specific authorization
Usage: 
# Server-side API call for specific connection
curl -H "Authorization: Bearer sk_prod_..." \
     -H "Connection-Token: con_tkn_..." \
     https://api.withterminal.com/tsp/v1/vehicles

​
Public Tokens

Public tokens function like authorization codes in an OAuth flow - they’re temporary tokens received from the consent process that you exchange for connection tokens. Characteristics:
  • Safe to transmit but intended for immediate exchange
  • Must be combined with a secret key to generate connection tokens
  • Cannot access data on their own
Usage: 
# Exchange a public token for a connection token
curl -X POST \
  -H "Authorization: Bearer sk_prod_..." \
  -H "Content-Type: application/json" \
  -d '{"publicToken": "pt_..."}' \
  https://api.withterminal.com/tsp/v1/public-token/exchange

​
Environment-Specific Keys

Terminal provides separate keys and API endpoints for different environments:
  • Production: Use production keys (prefixed with pk_prod_ and sk_prod_) for production applications
    • API Base URL: https://api.withterminal.com/tsp/v1
  • Sandbox: Use sandbox keys (prefixed with pk_sandbox_ and sk_sandbox_) for development and testing
    • API Base URL: https://api.sandbox.withterminal.com/tsp/v1