> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withterminal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate with Terminal using API keys and connection tokens

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](https://dashboard.withterminal.com/api-keys).

### Publishable Key

Your publishable key is used for client-side authentication from web browsers and mobile applications through the [consent flow](/terminal-platform/link).

**Characteristics:**

* Safe to expose in client-side code
* Used for browser-based integrations
* Can only create and re-connect connections

**Usage:**

```jsx theme={null}
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.

<Warning>
  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.
</Warning>

**Characteristics:**

* Must be kept secure on your servers
* Provide full API access
* Used for backend integrations and sensitive operations

**Usage:**

```bash theme={null}
# 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](/terminal-platform/link).

<Info>
  **Note:** Connection tokens do not expire unless rotation is explicitly
  requested. When a connection is disconnected and reconnected, the same token
  is retained.
</Info>

**Characteristics:**

* Specify which customer's data to access
* Provide connection-specific authorization

**Usage:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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](./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`