Leaf Provider Connection / Authentication Link

Overview

Leaf's Provider Connection / Authentication Link is a widget that you can install with minimal setup and a few lines of code. This widget enables your customers to connect their existing provider accounts, which associates it with their Leaf User.

Beta

This is a beta feature.

Get started

1. Sign in with a Leaf account

You will need a Leaf account. If you don't have one yet, you can create it here.

2. Get to know the Leaf user entity

All control of connected providers is done at the Leaf user level (usually it represents the user of your application), so it's important to know more about it here.

3. Create the user application tokens

Since the connection is at Leaf user level, the widget uses a different authentication method. We will required to create an API key for each Leaf user. This will ensure that the Leaf user only accesses its own resources.

The endpoints to manage those application tokens are here.

Set up

To use the widget you will need to enable the providers. Don't worry, you only need to set it up once.

John Deere

To enable John Deere as a provider in the widget you need your application already registed with John Deere. You can find more info on how to create a developer account here.

Redirect URI

The first step is to add our widget URL in the "Redirect URI" section:

https://widget.withleaf.io

In the My applications page, select your application and edit it to add the URL here

Application info

To allow the users to authenticate with John Deere, you will need to send your application info to this endpoint  POST /usermanagement/api/app-keys/JohnDeere/{appName}/{clientEnvironment}

For John Deere, it is necessary to inform the:

• clientKey (Application Id)
• clientSecret (Secret)

You can set the appName and the clientEnvironmentas the environment your application is enabled on John Deere: STAGE or PRODUCTION.

Here is a request example:

• cURL
• Python
• JavaScript

curl -X POST \

-H 'Authorization: Bearer YOUR_TOKEN' \

-d '{ "clientKey": "string", "clientSecret": "string" }'

'https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/LeafWidget/PRODUCTION'

Climate FieldView

To enable Climate FieldView as a provider in the widget you need your application credentials from Climate. You can find more info on how to create a developer account here.

Application info

To allow the users to authenticate with Climate FieldView, you will need to send your application info to this endpoint  POST /usermanagement/api/app-keys/ClimateFieldView/{appName}

For Climate FieldView, it is necessary to inform the:

• apiKey
• clientId
• clientSecret

You can set the appName.

Here is a request example:

• cURL
• Python
• JavaScript

curl -X POST \

-H 'Authorization: Bearer YOUR_TOKEN' \

-d '{ "apiKey": "string", "clientId": "string", "clientSecret": "string" }'

'https://api.withleaf.io/services/usermanagement/api/app-keys/ClimateFieldView/LeafWidget'

CNHi

To enable CNHi as a provider in the widget you need your application credentials from CNHi. You can find more info on how to create a developer account here.

Redirect URI

The first step is to add our widget URL in the "App OAuth Callback URL(s)" section:

https://widget.withleaf.io

In the Developer Dashboard page, select your application and edit it to add the URL here

Application info

To allow the users to authenticate with CNHi, you will need to send your application info to this endpoint  POST /usermanagement/api/app-keys/CNHI/{appName}/{clientEnvironment}

For CNHi, it is necessary to inform the:

• clientId (Client Id)
• clientSecret (Client Secret)
• subscriptionKey (Primary SubscriptionKey)

You can set the appName and the clientEnvironment as the environment your application is enabled on CNHi: STAGE or PRODUCTION.

Here is a request example:

• cURL
• Python
• JavaScript

curl -X POST \

-H 'Authorization: Bearer YOUR_TOKEN' \

-d '{ "clientId": "string", "clientSecret": "string", "subscriptionKey": "string" }'

'https://api.withleaf.io/services/usermanagement/api/app-keys/CNHI/LeafWidget/PRODUCTION'

AgLeader

To enable AgLeader as a provider in the widget you need your application credentials from AgLeader. You can find more info on how to create a developer account here.

Application info

To allow the users to authenticate with AgLeader, you will need to send your application info to this endpoint  POST /usermanagement/api/app-keys/AgLeader/{appName}

For AgLeader, it is necessary to inform the:

• privateKey
• publicKey

You can set the appName.

Here is a request example:

• cURL
• Python
• JavaScript

curl -X POST \

-H 'Authorization: Bearer YOUR_TOKEN' \

-d '{ "privateKey": "string", "publicKey": "string" }'

'https://api.withleaf.io/services/usermanagement/api/app-keys/AgLeader/LeafWidget'

Trimble

To enable Trimble as a provider in the widget you need your application credentials from Trimble. You can find more info on how to create a developer account here.

Application info

To allow the users to authenticate with Trimble, you will need to send your application info to this endpoint  POST /usermanagement/api/app-keys/Trimble/{appName}

For CNHi, it is necessary to inform the:

• applicationName
• clientId
• clientSecret

You can set the appName.

Here is a request example:

• cURL
• Python
• JavaScript

curl -X POST \

-H 'Authorization: Bearer YOUR_TOKEN' \

-d '{ "applicationName": "string", "clientId": "string", "clientSecret": "string" }'

'https://api.withleaf.io/services/usermanagement/api/app-keys/Trimble/LeafWidget'

Tutorial

This widget is only available for Angular.

Angular

To add this Leaf widget in an Angular application, you can use the @withleaf.io/angular-ui-kit library, which is a JavaScript library that provides all Leaf UI Widgets. Here are the general steps to get started:

1. Install the @withleaf.io/angular-ui-kit package using npm:

npm i @withleaf.io/angular-ui-kit

2. Import the library in your component or module file:

import { ProvidersModule } from '@withleaf.io/angular-ui-kit';

3. Add the component to the HTML. Make sure you already created the Leaf user API key (apiKey), you need to inform it and the Leaf user ID (leafUser) in the required properties in the HTML component. Just add it to the container div. You can also customize it adding your company name (companyName) and company logo (companyLogoUrl). Check all the properties available on the reference here.

<div class="container">

<leaf-providers leafUser="{leafUserId}" apiKey="{apiKey}"

companyName="{name}" companyLogoUrl="{image URL}">

</leaf-providers>

</div>

Reference

Property Overview

Name	Type	Summary
apiKey	String	The authentication API Key
companyLogoUrl	String	Customization: a link to the company logo
companyName	String	Customization: the name of the company
leafUser	String	The Leaf User ID

Property Details

apiKey

The apiKey is the authentication key that will allow the use of the widget. It can be created and managed here.

companyLogoUrl

The URL to the company logo. It will be displayed in the landing screen. It can be a PNG, JPEG or SVG.

companyName

The company name. It will be displayed in the landing screen and in each reference about the customer.

leafUser

The Leaf User ID. Check this page for more info about the Leaf User.

Event Overview

Name	Summary
complete	The authentication API Key

Event Details

complete

Fires after a user clicks in the "Done" button in the final screen. It will get access to all providers connected.