Authorization of Organizations

Overview

In order to gain access to an Organization’s data, a user of that Organization must authorize your application to do so. This is accomplished through an OAuth process, where the user will be directed to a Trimble Ag website. Here, the user is required to sign in, approve your application and select which Organizations to approve for access.

Step 1

From your application, or via another process of your choice, redirect the user that would be approving your application to the following URL:

URL for Authorization Code Grant

https://www.trimbleag.com/ThirdPartyAccess/ThirdPartyAuthorizationRedirect?clientid={{yourClientId}}&redirectionUrl={{authorizationRedirectUrl}}

URL for Client Credentials Grant

https://www.trimbleag.com/ThirdPartyAccess/ThirdPartyAuthorizationRedirect?clientid={{yourClientId}}

Step 2

Users who are not currently logged in are directed to Trimble’s login service for www.trimbleag.com.

Step 3

The logged-in user is presented with an Authorization page that uses the logo provided to Trimble as part of the Authorization setup.

Step 4

Once your application is authorized for that user, the user will be presented with a list of Organizations to which they have access and can select the Organizations to which they want your application to have access as well. Selecting a Trimble Ag Advisor Organization provides access to all the child Organizations that the logged- in user has access to for that Advisor Organization.

Step 5

This step only applicable for Authorization Code Grant

Once the user hits the save button after selecting the Organizations, they will be redirected to the authorization redirect URL that you provided during setup of your application with Trimble.

Step 6

Once the user has authorized you to access their data, you can expect the following:

Below applies to Authorization Code Grant

• The OrgIds authorized for that user will appear in the GET config/organizations result set.
• The returned results will be scoped to the token for that user. It is your responsibility to use the proper user token for matching the user in your system and use the refresh token before it expires.
• If the refresh token expires before you use it to acquire a new token, your system will need to acquire a new User Authorization Code to exchange for a new access and refresh token.
• User Authorization Code - Valid for 10 mins, Access Token - Valid for 1 hour, Refresh Token - Valid for 9 days.

Below applies to Client Credentials Grant

• The OrgIds authorized for that user will appear in the GET config/organizations result set.
• The returned results will be scoped to the list of orgs authorized to be accessed by your application.
• When the access token expires you will need to call the Authentication Token endpoint again to obtain a new access_code to use with the APIs.
• Access Token - Valid for 1 hour.

For each user that approves usage of their data, it is your responsibility to ensure that only the authorized user has access to the authorized data in your application.