CNHi authentication with Leaf

In this post, we are going to show you how to easily go through CNHi authorization flow with Leaf, that is, get authorization to access your users’ CNHi data with Leaf. We’ll be making some calls to Leaf, all endpoints can be found in our docs and Postman collection. Let’s get to it!

(Clique aqui para a tradução em português)

Summary

• Step 0: Create a developer account with CNHi
• Step 1: Get your CNHi developer credentials
• Step 2: Get your users’ CNHi tokens with Leaf.
• Step 3: Add CNHi credentials to Leaf.

Keep in mind that this tutorial is a full walkthrough. Most of the steps presented will be done only once, meaning that subsequent calls will be much easier and faster.

Step 0: Create a developer account with CNHi

(if you already have a developer account in CNHi, you can skip this step)

Creating a CNHi developer account is a very simple and automatic process, you can register here.

After that, you will have created your developer account and can go to the next step of this tutorial.

Step 1: Get your CNHi developer credentials

First, you have to login in your CNHi developer account. Head to the developer portal, click 'LOG IN' (top right corner) and log in.

Click in the user icon in the top-right, and in Account Dashboard:

Then, click “Add Application” and create a new application

Once it’s created, click on “App Registrations” and then in the application name:

Finally, click on “API Information” and you will find the Client ID, Client Secret and SubscriptionKey:

Awesome! Now you have your CNHi Client ID, Client Secret and SubscriptionKey. You will use them in the next step.

Step 2: Get your users’ CNHi tokens with Leaf

NOTE: While in the CNHi STG environment, you can only test with STG accounts, PROD customer accounts will not work. Once in PROD, STG testing accounts won’t work.

To get your users’ tokens to access their CNHi data, your application must go through CNHi OAuth flow. First, you need to redirect the user to a custom URL that is the CNHi page that will present the user the choice of authorizing your app to access their data.

At the end of this step, we will want to have retrieved your user’s CNHi refresh token.

To generate a refresh token, your webapp must direct users to the “Log in with CNHi” page. Once users authenticate on the CNHi site, they’ll be redirected back to your app with a code you’ll use to retrieve the required refresh token.

Here’s the Interactive login workflow:

The user arrives at your site and clicks the “Log in with CNHi” button. Clicking this button navigates the user’s browser to the CNHi login page. Leaf can help you construct the authorization URL. Send a POST request to:

with the following JSON body:

The client_redirect_url is the URL CNHi will send the user to after authentication. Remember that this URL must be set in the application creation (or editing the application’s configurations). The "production" parameter defaults to false since new applications in CNHi are in their stage environment by default, set it to true if you already promoted your application to production.

Leaf will return you a URL that you can send your user to, so the user can authorize access to their data and be redirected to your app.

Now, the last thing needed is to get the user’s refresh token. Once users log in on CNHi’s website link you created, they will authorize your application to access their data and they will be redirected back to “client_redirect_url” you set. Then, your application will use the response URL to get the user’s tokens. Send a POST request to:

with the following JSON body:

The response_url is the url you user is now. It’s the url that CNHi called to return to your website. CNHi adds information to that URL, information that is needed to create the token.

A JSON containing the refresth_token will be returned, and you can add them to Leaf as CNHi credentials.

Note: Leaf will manage tokens, making sure they are always refreshed and valid.

Step 3: Add your CNHi credentials to Leaf

Leaf’s API uses an abstraction called Leaf User to store credentials and organize data for each individual data owner. In most cases, the Leaf User will be the farmer or consultant that has access to the source data inside the machinery company’s FMIS (e.g. John Deere Operations Center or Climate Field View platform).

Leaf’s API must then be initiated with CNHi credentials in order to access and standardize CNHi data. To send your credentials to Leaf, you will need your access token from Leaf, and have already created a Leaf User. If you don’t know how to do that, here is how you get your access token, and here is how you create a Leaf User.

Now, attach your credentials to the Leaf User you created. Send a POST to

with the following Header:

and with the following JSON body:

Change "clientEnvironment" to "PRODUCTION" if your application is already in production in CNHi.

And that’s it! Now Leaf will start fetching your farm data from CNHi. You can now query Leaf for your standardized data.