Terminal Authentication API

The Authentication API from Terminal — 1 operation(s) for authentication.

GitHub OpenAPI

Operations 1

POST /public-token/exchange Public Token Exchange #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/terminal-telematics:terminal-telematics-authentication-api"
All apis
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.

Get an API 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 Specification

terminal-telematics-authentication-api-openapi.yml Raw ↑
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