Access

Access to Suite data through the CloudHub API follows a two-tier model. External applications authenticate to Trimble Transportation Cloud (TTC) using OAuth 2.0. The OData API enriches each request with account and tenant context, then forwards a licensed call to the on-premise Cloud Hub Connector (CHC), which validates an internal product license before executing the request against the Suite database.

Authentication and authorization flow

flowchart TB
  subgraph Client["Your application"]
      App["Integration app"]
  end

  subgraph TTC["Trimble Transportation Cloud"]
      Identity["Trimble Identity"]
      Gateway["TTC API gateway"]
      OData["OData API"]
      Config["CloudHub configuration"]
  end

  subgraph OnPrem["Customer site"]
      CHC["Cloud Hub Connector"]
      DB[("Suite database")]
  end

  App -->|"1. Request token"| Identity
  Identity -->|"access_token"| App
  App -->|"2. Bearer token"| Gateway
  Gateway -->|"3. Credential headers"| OData
  OData -->|"4. Resolve tenant"| Config
  Config --> OData
  OData -->|"5. InternalProductKey"| CHC
  CHC -->|"6. Query or update"| DB

  classDef auth fill:#e8f4fc,stroke:#0063a3,color:#171c1e
  classDef authz fill:#f0f4e8,stroke:#5a7a2e,color:#171c1e
  class Identity,Gateway auth
  class Config,CHC authz

The numbered steps above map to the request lifecycle:

Step	Layer	Authentication	Authorization
①–②	Trimble Identity / TTC gateway	Client ID and secret exchanged for a JWT; gateway validates the token	Token must include the `sas_token` scope
③–④	OData API	Reads JWT claims into credential headers	Resolves which CHC endpoint serves this account
⑤–⑥	Cloud Hub Connector	Validates `InternalProductKey` product license	All data access scoped to the customer’s Suite database

Request sequence

sequenceDiagram
  participant Client as Your Application
  participant Identity as Trimble Identity
  participant TTC as TTC API Gateway
  participant OData as OData API
  participant Config as CloudHub Configuration
  participant CHC as Cloud Hub Connector
  participant DB as Suite Database

  Client->>Identity: POST /oauth2/token
  Identity-->>Client: access_token
  Client->>TTC: GET /odata/carriers + Bearer token
  Note over TTC: Authenticates JWT
  TTC->>OData: x-credential-jwt, x-credential-account-id
  Note over OData: Parses claims, sets headers
  OData->>Config: Lookup tenant by account
  Config-->>OData: CHC endpoint
  OData->>CHC: InternalProductKey + OData request
  Note over CHC: Validates product license
  CHC->>DB: Query or update data
  DB-->>CHC: Results
  CHC-->>OData: Response
  OData-->>TTC: Response
  TTC-->>Client: Response

Direct CHC access (alternative path)

Internal services or on-premise integrations may call CHC directly, bypassing TTC. This path uses product licensing instead of OAuth.

flowchart LR
  Internal["Internal service"] -->|"InternalProductKey"| CHC["Cloud Hub Connector"]
  CHC --> DB[("Suite database")]

  classDef auth fill:#e8f4fc,stroke:#0063a3,color:#171c1e
  class CHC auth

Getting Access

This guide covers TTC provisioning and authentication for developers building integrations. On-premise CHC installation is a separate step performed by customer IT — see CHC Installation.

Before calling the API, the following must be in place for each customer environment:

Step	Who	What
1	Customer IT	CHC installed on-premise, connected to the Suite database, and publicly reachable over HTTPS
2	Trimble / integration team	TTC account and API Key application (client ID and secret) provisioned for the integration
3	Trimble / integration team	CloudHub configuration record in TTC that maps the account to the customer’s CHC OData endpoint

TTC account and API Key

Work with your Trimble representative to provision:

A TTC account for the customer environment
An API Key application (client ID and client secret) for the integration

Developers use the client ID and secret to obtain Bearer tokens from Trimble Identity. See Authentication below.

CloudHub Configuration

After CHC is installed and exposed, register a CloudHub configuration record that tells TTC where to route OData requests. Use the client ID and secret from the API Key application to send a request to /tte-tmwsuite/v0/configuration in the appropriate TTC environment. The cloudHubConnector.oDataEndpoint must match the public CHC URL provided during installation — see Making CHC publicly available.

Example configuration for a customer with a public CHC URL of https://test-dev.tmwcloud.com/chc:

{
  "cloudHubConnector": {
    "grpcEndpoint": "",
    "oDataEndpoint": "https://test-dev.tmwcloud.com/chc"
  },
  "defaultFlag": true,
  "nameValuePairsConfig": {},
  "premiseTimeZone": "Eastern Standard Time",
  "systemsLinkRestfulConfig": {
    "systemslinkUrl": "",
    "ttsUser": "",
    "ttsPassword": ""
  },
  "systemsLinkWCFConfig": {
    "systemslinkExternalUrl": "",
    "externalUser": "",
    "externalPassword": ""
  },
  "dataSync": {
    "fdsOrderDxTradingPartner": "SET_PER_CUSTOMER",
    "externalIntegrationSync": "CHC"
  }
}

Authentication

Via Trimble Transportation Cloud (recommended)

External integrations should call the OData API through TTC. Every request must include a Bearer token in the Authorization header:

Authorization: Bearer {access_token}

Obtain an access token from Trimble Identity using the OAuth 2.0 client credentials flow:

Setting	Value
Token URL (dev)	`https://cloud.dev.api.trimblecloud.com/transportation/api/identity/v2/oauth2/token`
Grant type	`client_credentials`
Scope	`sas_token`
Credentials	Client ID and client secret from your TTC API Key application

Example token request:

POST /transportation/api/identity/v2/oauth2/token HTTP/1.1
Host: cloud.dev.api.trimblecloud.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=sas_token&client_id={client_id}&client_secret={client_secret}

Example API call:

GET /transportation/tte-tmwsuite/v0/odata/carriers HTTP/1.1
Host: cloud.dev.api.trimblecloud.com
Authorization: Bearer {access_token}

What happens after you authenticate

TTC gateway validates the JWT (signature, expiry, and scope) before the request reaches the OData service.
OData API (AuthMiddleware) reads the token from either the Authorization: Bearer header or the x-credential-jwt header injected by TTC. It extracts JWT claims and sets internal credential headers:
- account_id → x-credential-account-id
- name → x-credential-application-name
- account_name → x-delegated-account-name
The OData service resolves the tenant CloudHub configuration for the account and sets x-configuration-id, which determines which CHC endpoint receives the forwarded request.
On the outbound call to CHC, the OData service automatically adds an InternalProductKey header — callers do not need to supply this when using the TTC path.

The OData service reads JWT claims to establish request context; cryptographic validation of the token is performed by the TTC gateway upstream.

Direct CHC access (on-premise / internal)

When calling Cloud Hub Connector directly — for example at https://{customer-host}/chc/v0/odata/carriers — authentication works differently. CHC does not accept Bearer tokens. Instead, every OData request must include an InternalProductKey header:

InternalProductKey: {encrypted-product-header}

CHC validates this header in LicensingValidationMiddleware. The value is an encrypted, time-limited internal product license token (approximately 15-minute TTL) generated using Trimble’s internal product helper library.

Result	HTTP status	Message
Header missing	403 Forbidden	Missing License!
Header invalid or expired	403 Forbidden	License validation failed!

Certain diagnostic endpoints (such as healthchecks, buildInfo, and $odata) are whitelisted and do not require the license header. This path is intended for internal Trimble services and direct on-premise integrations, not for external API consumers.

Authorization

Neither the OData API nor Cloud Hub Connector implements role- or scope-based authorization at the controller level. There are no per-user permission checks against Suite security roles in these services.

Instead, authorization is enforced through tenant isolation and licensing:

Layer	What is enforced
TTC / Trimble Identity	The calling application is authenticated; the token must be valid and include the `sas_token` scope.
CloudHub configuration	Each account is mapped to a specific CHC endpoint. A caller can only reach the Suite database configured for their account.
CHC product license	The `InternalProductKey` header confirms the request originates from a licensed Trimble product or service.
Suite database	CHC connects to a single customer database configured in `appsettings.json`. All data access is scoped to that database.

Account context from the JWT is used for audit logging and tenant routing, not for fine-grained data access control within Suite. If your integration requires user-level permissions (for example, restricting which carriers or companies a caller can see), that logic must be implemented in your application or enforced through Suite’s own security configuration.

API Endpoints

Access path	Base URL (dev)	Authentication
OData API via TTC	`https://cloud.dev.api.trimblecloud.com/transportation/tte-tmwsuite/v0/odata/`	`Authorization: Bearer {access_token}`
CloudHub API via TTC	`https://cloud.dev.api.trimblecloud.com/transportation/tte-tmwsuite/v2/` (Drivers v3: `/tte-tmwsuite/v3/`)	`Authorization: Bearer {access_token}`
OrderCreate API via TTC	`https://cloud.dev.api.trimblecloud.com/transportation/tte-tmwsuite/v0/automation/`	`Authorization: Bearer {access_token}`
Cloud Hub Connector (direct)	`https://{customer-host}/chc/v0/odata/`	`InternalProductKey: {encrypted-header}`

See the OpenAPI definitions for the complete list of endpoints. For integration design guidance, see Best Practices.