Terminal Authentication API
The Authentication API from Terminal — 1 operation(s) for authentication.
The Authentication API from Terminal — 1 operation(s) for authentication.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/terminal-telematics:terminal-telematics-authentication-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Terminal Telematics Authentication API
description: Terminal is a unified API that makes it easy to integrate with the leading telematics service providers.
version: '0.0'
contact:
name: Terminal
email: connect@withterminal.com
url: https://www.withterminal.com
servers:
- url: https://api.withterminal.com/tsp/v1
description: Production
- url: https://api.sandbox.withterminal.com/tsp/v1
description: Sandbox
security:
- Authorization: []
tags:
- name: Authentication
paths:
/public-token/exchange:
x-mcp:
enabled: true
post:
summary: Public Token Exchange
operationId: publicTokenExchange
x-operation-category: control-plane
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Connection'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/TooManyRequestsError'
'500':
$ref: '#/components/responses/InternalServerError'
'504':
$ref: '#/components/responses/GatewayTimeoutError'
description: Exchange the `publicToken` returned by our hosted authentication flow for a long lived connection token that will be used when requesting data from a customer's TSP.
tags:
- Authentication
requestBody:
content:
application/json:
schema:
type: object
properties:
publicToken:
$ref: '#/components/schemas/PublicToken'
required:
- publicToken
components:
schemas:
FullConnection:
title: Full Connection
description: The connection your application has with your customer's TSP.
allOf:
- title: Connection Base
type: object
description: Fields shared by all connection records.
properties:
id:
$ref: '#/components/schemas/ConnectionId'
company:
type: object
properties:
name:
type: string
example: Frank's Trucking
description: Optional name of the connection.
dotNumbers:
type: array
description: Optional DOT numbers associated with this connection.
items:
type: string
example: '1234567'
account:
type: object
properties:
name:
type: string
example: Frank's Trucking
description: The name of the account according to the provider.
dotNumbers:
type: array
description: DOT numbers associated with the account according to the provider.
items:
type: string
example: '1234567'
user:
type: object
description: The user of the provider account that created the connection.
properties:
sourceId:
description: The ID of the user in the provider's system.
example: '1234567'
type: string
firstName:
example: John
type: string
lastName:
example: Doe
type: string
email:
example: john.doe@example.com
type: string
provider:
type: object
required:
- code
- name
properties:
code:
$ref: '#/components/schemas/ProviderCode'
name:
type: string
example: Geotab
description: The name of the Telematics Service Provider.
externalId:
type: string
example: '1234'
description: An optional ID from your system that can be used to reference connections.
sourceId:
$ref: '#/components/schemas/SourceId'
description: 'The ID used in the source system to represent the account this connection has or had access to.
This may be an `organizationId` or `accountId`.
Note: not all systems expose this information, in which case it may be undefined.'
syncMode:
$ref: '#/components/schemas/SyncMode'
token:
type: string
example: con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4
pattern: ^con_tkn_\S+$
description: This token is used when interacting with a connections' data.
tags:
type: array
description: An optional list of tags from your system that can be used to reference connections.
items:
type: string
example: Tag Name
createdAt:
$ref: '#/components/schemas/ISODateTime'
updatedAt:
$ref: '#/components/schemas/ISODateTime'
required:
- id
- company
- account
- provider
- syncMode
- token
- createdAt
- updatedAt
- type: object
properties:
status:
type: string
enum:
- connected
- disconnected
- archived
- pending_deletion
description: The current status of the connection.
options:
$ref: '#/components/schemas/ProviderOptions'
filters:
$ref: '#/components/schemas/ConnectionFilters'
linkUrl:
type: string
format: uri
example: https://link.withterminal.com/connection/{CONNECTION_ID}?key={PUBLISHABLE_KEY}
description: The URL to send your user to in order to have them re-authenticate the connection.
required:
- status
- options
- linkUrl
SourceId:
title: SourceId
type: string
example: '123456789'
description: The ID used to represent the entity in the source system.
Connection:
title: Connection
x-model-category: platform
oneOf:
- $ref: '#/components/schemas/FullConnection'
- $ref: '#/components/schemas/DeletedConnection'
x-description: The connection your application has with your customer's TSP.
PublicToken:
title: Public Token
type: string
example: pub_tkn_9jNzH26e5b9RgErDnRt8zfm5emDUUyyG
description: Token returned by the authentication flow. Public tokens are one time use and expire after they are exchanged for a long-lived connection token.
pattern: ^pub_tkn_\S+$
ProviderOptions:
type: object
oneOf:
- type: object
properties:
ingestHistoryFromSourceSystem:
default: true
description: By default our system will ingest Vehicle Locations and Stat Logs from the source system. Omnitracs also supports history at a higher sample rate through a historical file process. If you are using these historical files and want to avoid mixing the data sources, set this to false.
type: boolean
required: []
title: Omnitracs Options
- type: object
properties:
ingestHistoryFromSourceSystem:
default: true
description: By default our system will ingest Vehicle Locations and Stat Logs from the source system. Omnitracs also supports history at a higher sample rate through a historical file process. If you are using these historical files and want to avoid mixing the data sources, set this to false.
type: boolean
required: []
title: Omnitracs ES Options
- type: object
properties:
ingestHistoryFromSourceSystem:
default: true
description: By default our system will ingest Vehicle Locations and Stat Logs from the source system. Omnitracs also supports history at a higher sample rate through a historical file process. If you are using these historical files and want to avoid mixing the data sources, set this to false.
type: boolean
required: []
title: Omnitracs XRS Options
ErrorPathDetail:
title: ErrorPathDetail
type: object
properties:
message:
type: string
example: '''vehicleId'' property must be a valid ulid'
path:
type: string
example: '{requestQuery}.vehicleId'
suggestion:
type: string
example: Please ensure you submit a valid 'vehicleId' property
context:
type: object
required:
- message
- path
ConnectionFilters:
type: object
properties:
vehicles:
type: object
properties:
status:
type: string
enum:
- active
- inactive
description: Filter connection to only include data related to vehicles with a specified status
excludeIds:
type: array
items:
$ref: '#/components/schemas/VehicleId'
description: IDs of vehicles to exclude from data ingestion
includeIds:
type: array
items:
$ref: '#/components/schemas/VehicleId'
description: IDs of vehicles to include in data ingestion (takes priority over other filters)
drivers:
type: object
properties:
status:
type: string
enum:
- active
- inactive
description: Filter connection to only include data related to drivers with a specified status
excludeIds:
type: array
items:
$ref: '#/components/schemas/DriverId'
description: IDs of drivers to exclude from data ingestion
includeIds:
type: array
items:
$ref: '#/components/schemas/DriverId'
description: IDs of drivers to include in data ingestion (takes priority over other filters)
description: 'Filters applied to connection data. Across all lists, the maximum is about 8,000 IDs. A larger update is rejected with 422 and is not saved. If one list contains most vehicles or drivers, use the opposite list: excludeIds for the ones to skip, or includeIds for the ones to keep.'
DeletedConnection:
title: Deleted Connection
description: A retained connection record after connection-scoped data has been deleted.
allOf:
- $ref: '#/components/schemas/FullConnection/allOf/0'
- type: object
properties:
status:
type: string
enum:
- deleting
- deleted
deletedAt:
$ref: '#/components/schemas/ISODateTime'
description: When Terminal finished deleting connection-scoped data. Present once status is `deleted`.
required:
- status
DriverId:
title: DriverId
description: Unique identifier for the driver in Terminal.
type: string
format: ulid
pattern: ^drv_[0-9A-HJKMNP-TV-Z]{26}$
example: drv_01D8ZQFGHVJ858NBF2Q7DV9MNC
SyncMode:
title: SyncMode
type: string
enum:
- automatic
- manual
description: 'Enum values:
- `automatic`: Terminal will keep this connections data up to date
- `manual`: Terminal will only sync data upon request'
default: automatic
ConnectionId:
title: ConnectionId
type: string
format: ulid
example: conn_01GV12VR4DJP70GD1ZBK0SDWFH
ProviderCode:
type: string
example: geotab
description: Every provider has a unique code to identify it across Terminal's system. You can find each provider's code under [provider details](/providers).
ISODateTime:
title: ISODateTime
type: string
format: date-time
example: '2021-01-06T03:24:53.000Z'
description: '[ISO 8601](https://www.w3.org/TR/NOTE-datetime) date'
VehicleId:
title: VehicleId
description: Unique identifier for the vehicle in Terminal.
type: string
format: ulid
pattern: ^vcl_[0-9A-HJKMNP-TV-Z]{26}$
example: vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC
responses:
ForbiddenError:
description: Forbidden
content:
application/json:
schema:
type: object
properties:
code:
enum:
- forbidden
message:
type: string
example: Forbidden Request
detail:
type: string
example: Please ensure the connection token matches the resource you are attempting to access.
required:
- code
- message
BadRequestError:
description: Bad Request
content:
application/json:
schema:
type: object
properties:
code:
enum:
- bad_request
message:
type: string
example: Invalid request body
detail:
type: array
items:
$ref: '#/components/schemas/ErrorPathDetail'
required:
- code
- message
GatewayTimeoutError:
description: Gateway Timeout Error
content:
application/json:
schema:
type: object
properties:
code:
enum:
- gateway_timeout
- provider_timeout
description: '`provider_timeout` means the telematics provider did not respond in time, or responded too slowly to finish the request (for example, while paginating). Retry later or narrow the request, for example with a shorter time range or smaller `limit`. `gateway_timeout` means Terminal could not finish the request in time for another reason.'
message:
type: string
example: Gateway Timeout
required:
- code
- message
UnauthorizedError:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
code:
enum:
- unauthorized
message:
type: string
example: Unauthorized Request
detail:
type: string
example: Please ensure you have a valid API key
required:
- code
- message
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
code:
enum:
- internal_server_error
message:
type: string
example: Internal Server Error
detail:
type: string
example: Something went wrong
required:
- code
- message
NotFoundError:
description: Not Found
content:
application/json:
schema:
type: object
properties:
code:
enum:
- not_found
message:
type: string
example: Resource not found
detail:
type: string
example: 'Could not find resource with ID: 2342342'
required:
- code
- message
TooManyRequestsError:
description: Too Many Requests
content:
application/json:
schema:
type: object
additionalProperties: true
properties:
code:
enum:
- too_many_requests
retryAfter:
description: The number of seconds to wait before retrying the request
type: integer
example: 60
message:
type: string
example: Too Many Requests
detail:
type: string
example: You have exceeded your rate limit. Please try again later.
required:
- code
- message
securitySchemes:
Authorization:
type: http
scheme: bearer