Client Credentials Grant - Authentication
Detailed Instructions to Authenticate Application
Overview and When to Use
These instructions apply to API partners that are configured to use the Client Credentials Grant for authentication and authorization instructions.
For more information on Client Credentials Grant configuration see here (this should link to “Client Credentials Grant” under “Grant Type Options).
Definition of Variables
Variables | Definition |
---|---|
TID - Trimble Identity Env Auth root | Production authentication - https://id.trimble.com |
yourAppName | The application name provided by Trimble that is assigned to your application |
yourClientId | The GUID (unique identifier) provided by Trimble that is assigned to your application |
accessToken | The JWT token that is used to access data endpoints. The access token has a 1 hour expiration. |
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.
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
https://id.trimble.com/oauth/authorize
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.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:
Attribute | Description | Values | Required |
---|---|---|---|
Authorization | Basic Auth using Base64 encoded value of provided ClientID | Basic Encoded value goes here | Y |
Content-Type | Specifies the request content type | application/x-www-form-urlencoded | Y |
Parameter Values
The web service expects the following fields as query string parameters:
Attribute | Description | Values | Required |
---|---|---|---|
grant_type | Required value to identify authentication type | client_credentials | Y |
scope | The name of your application | yourAppName | Y |
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:
Attribute | Description | Values |
---|---|---|
access_token | The security token that is used on subsequent requests. | This token will be a long string generated with each new POST to this endpoint. |
token_type | Identifier of what type of token has been returned. | Will always be “bearer” |
expires_in | Time 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. |
error | The Error title of the error being shown. | |
error_description | Error description to help understand the error provided. |
Response example (tokens truncated)