In this post, we are going to show you how to easily go through Climate FieldView authorization flow with Leaf, that is, get authorized to access your users’ Climate FieldView data with Leaf. Let’s get to it!
(Clique aqui para a tradução em português)
- Step 0: Create a developer account with Climate FieldView, get your application credentials and verify your scopes.
- Step 1: Get your users’ Climate FieldView tokens with Leaf.
- Step 2: Add Climate FieldView 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 Climate FieldView and get your application credentials.
(If you already have a developer account with Climate FieldView, you can skip this step)
To start the process to setup your Cliamte FieldView developer acount, you can register with this link.
After being approved by Climate FieldView, you will receive a clientId, a clientSecret, and an API Key.
Note: Before you proceed, we recommend you email developer@climate.com and verify you have the correct scopes.. "asHarvested:read", "asPlanted:read", "asApplied:read", "fields:read", "resourceOwners:read", "farmOrganizations:read"
Step 1: Get your users’ Climate FieldView tokens with Leaf.
To get your users’ tokens to access their Climate FieldView data, your application must go through Climate FieldView OAuth flow. You'll need to redirect the user to a custom URL that will present the user the choice of authorizing your app to access their data.
To get the URL for this authentication step, send a POST to https://cfv-oauth2-helper.withleaf.io/url with the following JSON:
If you prefer, you can also include the pass_through parameter, to inform the desired state after the authentication.
Leaf will create an URL containing the minimum scopes (permissions) necessary to fetch Fields, Farms and Operations. Leaf also supports the upload of Fields, Soil and GeoTiff data. If you want to be able to access those extra features, add "scope" to the request body including the base scopes and the scopes for writing fields, soil and imagery. The request body to fetch an URL with the extra scopes should be:
Note that the scopes for the extra features (fields:write, soil:write and imagery:write) may also require additional permissions from Climate FieldView. Ensure that you are allowed to ask for those scopes before generating a URL with them, and contact Climate FieldView to request permission in case you are not.
Leaf will return a URL that you can send your user to, so they can authorize access to their data and be redirected to your app. Note that Climate FieldView will redirect your user to the "redirect_uri" and also send a code that you will need to make a request to get your users' tokens.
Get the user’s tokens
Now we need to get the user’s tokens. Once users log in to Climate FieldView's website link you created, they will authorize your application to access their data and they will be redirected back to the "redirect_uri" you set, linked with a code (like this "https://withleaf.io/?code=AKgMaOmHa1zHxAoOoH"). Then, your application will use this code present in the response URL to get the user’s tokens.
Just send a POST to https://api.climate.com/api/oauth/token with the following header:
This requires you to encode “clientId:clientSecret” (your cliendId and clientSecret from the first step, separated by “:”) to base64. Most programming languages will have a way to encode text to base64, but if you want to do it manually you can use this website
Also, include the following body (x-www-form-urlencoded):
A JSON containing the tokens will be returned, and you can add them to Leaf as Climate FieldView credentials.
Note: Leaf will manage each and every token, making sure they are always refreshed and valid.
Step 2: Add your Climate FieldView 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 FieldView platform).
Leaf’s API must then be initiated with Climate FieldView credentials in order to access and standardize Climate FieldView 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 https://api.withleaf.io/services/usermanagement/api/users/yourLeafUserId/climate-field-view-credentials with the following header:
and with the following JSON body:
Excellent
Now Leaf will start fetching your farm data from Climate FieldView. You can now query Leaf for your standardized data.
Software developers use Leaf’s API to build and scale a wide range of products including farm optimization tools, lending products, outcome-based financing, land and input marketplaces, agronomic recommendations, traceability applications, equipment maintenance forecasting, and more.
