Authorization Code Grant - Authentication

Detailed Instructions to Authenticate Application

Overview and When to Use

Most API partners are configured to use the Authorization Code Grant and should use these instructions for authentication and authorization instructions.

Definition of Variables

VariablesDefinition
TID - Trimble Identity Env Auth rootProduction authentication - https://id.trimble.com
Trimble Ag API Env Data rootProduction data - https://cloud.api.trimble.com/Trimble-Ag-Software/externalApi/3.0
yourAppNameThe application name provided by Trimble that is assigned to your application
yourClientIdThe GUID (unique identifier) provided by Trimble that is assigned to your application
authenticationCallbackURLThe URL that users should be returned to from OAuth login at TID (must be an exact match to a URL in the list of valid authenticationCallback URLs you provide)
authorizationRedirectURLThe URL that users should be redirected to after authorizing Organizations for data access at www.trimbleag.com (must be an exact match to a URL in the list of valid authorizationRedirectURLs you provide)
authProviderThe returned value of the authentication provider that was accessed
TIDAuthCodeThe code generated by the TID system that you can exchange for an access, refresh and ID token from TID. This code may only be used once and expires after 10 minutes.
accessTokenThe JWT token that is used to access data endpoints. The access token has a 1 hour expiration.
idTokenThe JWT token contains additional information about the user who was authenticated in TID.
refreshTokenThe token has a 7-day expiration that can be exchanged for a new access token.

Authentication

In order for your application to access data within an Organization, the Trimble user must approve your application in an Authorization step, but in order to discover if a user has authorized your application you need to go through an OAuth process to gain access to the data that is scoped to that user.

These flow diagrams illustrate how you can use the APIs to allow third-party software to send data to and receive data from the Connected Farm software.

User Authorization Code

Step 1

The first step of the OAuth process is to send the user to log into Trimble’s identity management system in order to obtain an authorization code. This code will be valid for 10 minutes.

URL

Use this GET call to redirect the user to TID.

Terminal window
https://id.trimble.com/oauth/authorize?
scope={{yourAppName}} openid&
response_type=code&
redirect_uri={{authenticationCallbackUrl}}&
client_id={{yourClientId}}

Step 2

After the user logs into TID they will be returned to your application via the following URL:

{{authenticationCallbackUrl}}?code={{TIDAuthCode}}&identity_provider={{authProvider}}

Authentication Token API

This API can be used for authentication from a third party client application or a web service to obtain an access token to use for subsequent method calls as described in the Common authentication token. This API also returns an ID for identification and a refresh token for re-authentication after the access token expires. The authentication token is valid for 1 hour and the refresh token is valid for 9 days. The refresh token is a single-use token that becomes invalid after use.

URL

This URL should be used to obtain an authentication token and the refresh token.

POST {{Env Auth root}}/oauth/token

Input Example

The following is an example of the parameters to help illustrate the definition. The string of characters after the word Basic would be the result of base 64 encoding MyProvidedClientId

which you would replace with your own values.

POST: https://id.trimble.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic TXlQcm….
grant_type=authorization_code&code=sd3ds…&client_id=e3rdfF…&redirect_uri=https://mydomain.com/oauthreturn

The header and request body values are defined in the following tables.

Header Values

This web service expects you to post a URL-Form-Encoded string in the request body, containing the following fields in the header:

AttributeDescriptionValuesRequired
AuthorizationBasic Auth using Base64 encoded value of provided ClientID
Basic Encoded value goes hereY
Content-TypeSpecifies the request content typeapplication/x-www-form-urlencodedY

Request Body Values

This web service expects you to post a URL- Form- Encoded string in the request body, containing the following fields:

AttributeDescriptionValuesRequired
grant_typeRequired value to identify authentication typeauthorization_codeY
codeThe authorization code returned from the OAuth processTIDAuthCodeY
client_idThe GUID provided to youyourClientIdY
redirect_uriAn exact match to one of the URLs provided to Trimble by you to return to your app after logging in.authenticationCallbackUrlY

Response

This service acknowledges with an HTTP code 200 for success (OK) and all other HTTP codes for failure.

In addition to the 200 HTTP code, the web service responds with a JSON formatted document with the following fields to provide either confirmation of the receipt or an error:

AttributeDescriptionValues
access_tokenThe security token that is used on subsequent requests.This token will be a long string generated with each new POST to this endpoint.
token_typeIdentifier of what type of token has been returned.Will always be “bearer”
expires_inTime in seconds until expiration.Returns “3600”. Each call to the endpoint results in a new token lasting 60 minutes. Please cache and reuse the token for calls within 60 minutes of the last authentication.
id_tokenJWT token to provide additional information about the user.This token will be a long string generated with each new POST to this endpoint.
refresh_tokenToken to exchange for a new access token and refresh token.This token will be a string generated with each new POST to this endpoint.
errorThe Error title of the error being shown.
error_descriptionError description to help understand the error provided.

Response example (tokens truncated)

Content-Type: application/json; charset=utf-8
{
"token_type": "bearer",
"expires_in": 3600,
"access_token": "eyJ0eXAiOiJKV1….",
"refresh_token": "NAwdjwEX6vj….",
"id_token": "eyJ0eXAiOiJKV1QiLCJhb….",
}

Refresh Authentication Token API

URL

Use the following URL to obtain a refresh token once the authentication token expires.

POST {{Env Auth root}}/oauth/token

Input example

The following is an example of the parameters to help illustrate the definition. The string of characters after the word Basic would be the result of base 64 encoding MyProvidedClientId

are replaced with your own values.

Header Values

The web service expects you to post a URL- Form- Encoded string in the body, containing the following header values:

AttributeDescriptionValuesRequired
AuthorizationBasic Auth using Base64 encoded value of provided ClientID
Basic Encoded value goes hereY
Content-TypeSpecifies the request content typeapplication/x-www-form-urlencodedY

Body Values

The web service expects you to post a URL-Form-Encoded string in the body, containing the following fields:

AttributeDescriptionValuesRequired
grant_typeRequired value to identify authentication type.refresh_tokenY
refresh_tokenThe refresh code returned from the Authentication Token [link inserted here] endpoint.RefreshTokenY
tenantDomain*Required valuetrimble.comY

Response

The service sends an acknowledgement with HTTP code 200 for success (OK) and any other HTTP code for failure.

In addition to the HTTP 200 code, the web service responds with a JSON formatted document with the following fields to provide either confirmation of the receipt or an error:

AttributeDescriptionValues
access_tokenThe security token that is used on subsequent requests.This token will be a long string generated with each new POST to this endpoint.
token_typeIdentifier of what type of token has been returned.Will always be “bearer”
expires_inTime in seconds until expiration.Returns “3600”. Each call to the endpoint results in a new token lasting 60 minutes. Please cache and reuse the token for calls within 60 minutes of the last authentication.
id_tokenJWT token to provide additional information about the user.This token will be a long string generated with each new POST to this endpoint.
refresh_tokenToken to exchange for a new access token and refresh token.This token will be a string generated with each new POST to this endpoint.
errorThe Error title of the error being shown.
error_descriptionError description to help understand the error provided.

Response example

Content-Type: application/json; charset=utf-8
{
"token_type": "bearer",
"expires_in": 3600,
"access_token": "eyJ0eXAiOiJKV1....",
"refresh_token": "NAwdjwEX6vj....",
"id_token": "eyJ0eXAiOiJKV1QiLCJhb....",
}

Common Authentication Token

All REST calls made available by the Connected Farm data center will require proper authentication. To achieve this, a Trimble Identity access token must be passed to validate that the caller has permission. All subsequent calls are validated by Trimble’s TID service and the access token should be prefixed with Bearer in the Authorization header. The following is an example of the parameters to help illustrate the definition:

GET:
https://cloud.api.trimble.com/Trimble-Ag-Software/externalApi/3.0/config/organizations
Authorization: Bearer
eyJ0eXAiOiJK....