End User Integration Guide

The TForce Freight API third party integration guide is a high-level walkthrough of how the integration points in our API ecosystem empower your organization's applications to access and update your account information.

If your organization needs to provide services to TForce Freight customers by accessing account information on their behalf in your application, visit our Third Party Integration Guide instead.

Overview

The TForce Freight API is secured by the Microsoft Identity Platform using industry-standard OpenID Connect and OAuth protocols to provide authentication and authorization for your requests. Using your developer portal profile, you can discover and configure the details needed to successfully create requests to the APIs published here.

This guide details the requirements for configuring your application registration in our developer portal and using the information presented to obtain tokens to retrieve and update your TForce Freight account data.

Configuring Your Application

To configure your application, begin by navigating to your developer portal profile and clicking the Configure My Client button. The OAuth Client dialog contains various configuration elements that enable application authorization described below by section.

Your OAuth Client

This section provides a singular configuration point for labeling your application in the TForce Freight CIAM platform. Provide the following information in this section as described:

• Display Name: A descriptive name for the application to help TForce Freight support identify your integration.

Application Integration

Information in this section is intended to assist with providing your application endpoints to conduct OAuth token requests to consume TForce Freight APIs. There is no information to configure in this section.

OAuth Client Secrets

This section provides features to review and maintain client secrets for OAuth protocol exchanges with the TForce Freight CIAM platform. When creating a new secret, you can label your secrets with a name in the Description field to remind you which subsystem may use the secret to request tokens, as well as provide a lifetime in the Expires field when the secret will automatically expire.

⛔ CRITICAL
Client secret values can only be viewed immediately following creation. Be sure to save your newly created secrets before leaving this page.

The Secret ID column in the secrets table is only an informational identifier and will never be used in in OAuth protocol exchanges. If a secret is expired or has become compromised, it can be deleted using the delete button at the end of each secret detail row.

Obtaining an Access Token

The TForce Freight CIAM platform utilizes the Client Credentials flow provided by Azure Active Directory to generate tokens representing your confidential client application's access level when communicating with TForce Freight APIs. As this flow is provided by the Microsoft Identity Platform, the Microsoft Authentication Library (MSAL) is an excellent tool to leverage in order to simplify your consumption of the OAuth exchange and manage the lifetime of the returned tokens. The library is available to multiple application development languages such as C#, Java, Node.js, and Python. Additional links to code samples for this flow are available at the MSAL samples directory.

The remainder of this article will explain how to consume the flow in the absence of an acceptable library implementation for your application development stack.

Creating a Token Request

A token request for the client credentials flow composes the information from the OAuth Client dialog in your profile to receive an access token for your confidential client application in response. The JWT returned will have a lifetime of 60 minutes. Your application should manage this token lifetime and make additional requests for new tokens when the previous token's lifetime has ended.

The client credentials flow utilizes the OAuth token endpoint of the TForce Freight CIAM platform, taking the following parameters as application/x-www-form-urlencoded content at the POST HTTP method of the token endpoint:

• client_id: The Client ID of your application from the OAuth Client dialog.

• client_secret: A secret you created in the OAuth Client Secrets section of the OAuth Client dialog.

• grant_type: Use the value client_credentials to indicate you wish to obtain a token representing your confidential client application.

• scope: Use the Scope value from the Application Integration section your OAuth Client dialog to generate an access token. The scope value ending with .default indicates that you wish to receive all roles granted to your application in the returned token. End user applications will receive the Customer.All role on the TForce Freight API gateway at a minimum, and the JWT may contain other roles when specialized API access is required for your organization.

A sample request for the client credentials flow follows. Use the Token Endpoint from the Application Integration section of your OAuth Client dialog as the URL for this request.

//line breaks for legibility only

POST /ca4f5969-c10f-40d4-8127-e74b691f95de/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=3c29446e-153e-4b92-8f06-c453f117b645
&client_secret=3e04~5e12339444d1852d73bb33e9.3cf2
&grant_type=client_credentials
&scope=https://tffproduction.onmicrosoft.com/f06cb173-a8e6-44ad-89a1-06c1070a1f62/.default

If you have included the scope indicated above, along with valid OAuth client information, the response should be similar to the following sample:

Content-Type: application/json

{
    "token_type": "Bearer",
    "expires_in": 3599,
    "ext_expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ii1LSTNROW5OUjdiUm9meG1lWm9YcWJIWkdldyJ9..."
}

Managing Tokens

When implementing your integration with the TForce Freight API gateway, you must manage aspects of storing, retrieving, and refreshing the tokens that grant your application access to your organization's data.

The value of the access_token property can be used immediately for requests from your confidential client application to the TForce Freight API gateway. Once the lifetime of the token has expired, your application must issue another token request to obtain a new access token.

Access tokens issued by the TForce Freight CIAM platform are typically lived for one hour. This is indicated in the token response via the expires_in property. However, to ensure the most accurate understanding of the token's lifetime, decode and deserialize the access token you receive in the token response, and determine the expiry time by calculating it from the Unix epoch datetime expressed by the exp claim value. It may be helpful to store this information along with the raw token to speed evaluation of the token lifetime when communicating with the TForce Freight API gateway.

When creating a new request to the TForce Freight API gateway, inspect the expiry of the access token you have stored for the application. If the token is expired, follow the steps in the preceding section to obtain a new access token.

Once you have a token with a valid lifetime, create your request to the TForce Freight API gateway, appending an Authorization header using the Bearer scheme followed by the encoded token value, as below:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ii1LSTNROW5OUjdiUm9meG1lWm9YcWJIWkdldyJ9...

Additional Resources

Microsoft identity platform and the OAuth 2.0 client credentials flow (Link)

Overview of the Microsoft Authentication Library (MSAL) (Link)