Getting started

Sign up

Open the Application URL on your web browser and complete sign-up at https://web.connect.trimble.com.

Trimble-internal integrators can also use the staging environment at https://web.stage.connect.trimble.com - you need a separate sign-up for staging.

Register application

Please register your application by following the instructions at https://connect.trimble.com/integrator-sign-page.

With this information, we will register your application, and then share back a Consumer Key, Consumer secret, Application name & Callback url you will use to authenticate with Trimble Identity to use the Trimble Connect APIs.

Notice! For desktop applications, the callback url must be a local one (http://localhost) since a local port listener is needed to intercept the OAuth callback.

Notice! It is possible to register multiple callback urls. After receiving the initial application credentials, send a request to connect-integrate@trimble.com.

Trimble-internal integrators can register your application with Trimble Identity via self-service here https://console.trimble.com.

Get Access token

Once the above steps are completed, you should have the following details:

• Trimble Identity username (email)
• Trimble Identity password
• Application Name
• Application Consumer Key
• Application Consumer Secret
• Application Redirect/Callback Uri

Authentication

To use Trimble Connect APIs you need a user-context OAuth access token from Trimble Identity.

See the Authentication Guide for information on how to authenticate users with Trimble Identity using OAuth. Either Authorization Code with PKCE (recommended) or Authorization Code flows should be used.

To allow testing the APIs with Postman, the Postman callback url (https://oauth.pstmn.io/v1/browser-callback) is also configured for your application.

After successful authentication you’ll receive an access token that can be used to authorize Connect API calls.

Non-interactive authentication

Since Connect does not support OAuth Client Credentials tokens, any non-interactive applications/integrations need to use a different authentication approach:

1. Use the Authorization Code flow (as elsewhere)
2. The initial authentication needs to be interactive, you’ll receive an (access, refresh token) pair
3. Provision the non-interactive application with the (access, refresh token) pair
4. Properly manage the (access, refresh token) pair within the non-interactive application, refreshing as needed with a max 9 day interval to keep the tokens alive.

Notice! Both tokens change over time, so they need to be securely persisted

Use Access token

To use the Trimble Connect APIs, you will need to add the Authorization header to your requests. Replace ‘access_token’ with the actual value you get from the previous step.

Example: You can use the get user details API to validate that your authentication has been successful

GET https://app.connect.trimble.com/tc/api/2.0/users/me
Authorization: Bearer access_token

Example: You can get the list of projects in the US region with

GET https://app.connect.trimble.com/tc/api/2.0/projects?fullyLoaded=false
Authorization: Bearer access_token

Authorization

The Service API methods must be called as an authenticated Trimble Identity (TID) user. You need to complete the steps in on this page to be able to call the API.

Access to data is based on the authenticated user making the Connect API calls.

Generally, most data resides under a project. Project membership grants users access to project data. Read/write access to project data can be separately controlled by permissions. Project admins have full access to data in a project. Account admins have full visibility into projects created under the account. See the Concepts section for more details.