Skip to main content
Leaf Link is a set of drop-in UI widgets that handle two tasks: connecting your users’ provider accounts and uploading machine files. Leaf provides React and Angular packages, with provider availability depending on the package and widget runtime.

​
Widgets

Leaf Link includes two widgets:
  • Provider Connection lets your users authenticate with CNHi, John Deere, Trimble, Climate FieldView, AgLeader, Raven Slingshot, Lindsay, and Stara from inside your application.
  • File Upload lets your users drag-and-drop or browse for .zip files containing machine data. Leaf processes these files through the standard conversion pipeline.
Both widgets authenticate using a per-Leaf-user API key (not your API Owner bearer token). Create API keys via the API Key endpoints.

​
Prerequisites

  1. A Leaf account with at least one Leaf user created.
  2. A Leaf user API key (created via POST /api-keys).
  3. For provider connection: provider app credentials registered with Leaf for each provider you want to enable.

​
Provider setup

Each provider requires a one-time registration of your application credentials with Leaf. You also need to add https://widget.withleaf.io as a redirect/callback URL in the provider’s developer portal.
ProviderRedirect URL fieldCredentials needed
John DeereRedirect URIclientKey, clientSecret
Climate FieldView(none required)apiKey, clientId, clientSecret
CNHiApp OAuth Callback URL(s)clientId, clientSecret, subscriptionKey
AgLeaderRedirection URLprivateKey, publicKey
TrimbleAuthentication Callback URLapplicationName, clientId, clientSecret
Raven Slingshot(none required)apiKey, sharedSecret
LindsayRedirect URIclientId, clientSecret
Stara(none required)user, pwd
Register credentials by calling POST /usermanagement/api/app-keys/{Provider}/{appName} with the provider-specific fields. 
curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{"clientKey": "your-app-id", "clientSecret": "your-secret"}' \
  'https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/MyApp/PRODUCTION'

​
Installation

​
React

npm i @withleaf/leaf-link-react
Provider Connection: 
import { Providers } from "@withleaf/leaf-link-react";

function App() {
  return (
    <Providers
      isDarkMode={false}
      companyName="Acme Ag"
      companyLogo="https://example.com/logo.svg"
      leafUser="your-leaf-user-id"
      apiKey="your-leaf-user-api-key"
    />
  );
}
File Upload: 
import { FileUpload } from "@withleaf/leaf-link-react";

function App() {
  return (
    <FileUpload
      isDarkMode={false}
      companyName="Acme Ag"
      companyLogo="https://example.com/logo.svg"
      leafUser="your-leaf-user-id"
      apiKey="your-leaf-user-api-key"
      filesTimeRange={30}
    />
  );
}

​
Angular

npm i @withleaf/leaf-link-angular
Provider Connection: 
import { ProvidersModule } from "@withleaf/leaf-link-angular";

<providers
  apiKey="your-leaf-user-api-key"
  leafUser="your-leaf-user-id"
  companyName="Acme Ag"
  companyLogo="https://example.com/logo.svg"
></providers>
File Upload: 
import { FileUploadModule } from "@withleaf/leaf-link-angular";

<file-upload
  apiKey="your-leaf-user-api-key"
  leafUser="your-leaf-user-id"
  companyName="Acme Ag"
  companyLogo="https://example.com/logo.svg"
  [filesTimeRange]="30"
></file-upload>

​
Properties

​
Provider Connection

PropertyTypeDescription
apiKeyStringLeaf user API key (required)
leafUserStringLeaf user ID (required)
companyNameStringYour company name, displayed in the widget
companyLogoStringURL to your company logo (PNG, JPEG, or SVG)
isDarkModeBooleanEnable dark mode. Default: false
localeStringForce language: en_US, pt_BR, es_ES, or fr_FR. Defaults to browser language
titleStringWidget title. Default: “Select your integration”
showSearchbarBooleanShow/hide the provider search bar. Default: true
allowedProvidersstring[]Restrict the widget to a specific list of providers
fastModeBooleanEnable the widget’s fast mode behavior
applicationsArray<{ appName: string; provider: string; clientEnvironment: string }>Preload provider app settings for the widget

​
File Upload

PropertyTypeDescription
apiKeyStringLeaf user API key (required)
leafUserStringLeaf user ID (required)
companyNameStringYour company name
companyLogoStringURL to your company logo
isDarkModeBooleanEnable dark mode. Default: false
localeStringForce language
titleStringText displayed at the top of the widget
filesTimeRangeNumberDays of upload history to display

​
Hooks

Both widgets expose hooks for tracking widget state in your application.

​
Provider Connection hooks

Use useLeaf() from @withleaf/leaf-link-react:
HookTypeDescription
providersConnectedstring[]Provider names connected after the flow completes
providerWidgetStatus{ code: number; message: string }Widget status: -1 Error, 0 Started, 1 Done

​
File Upload hooks

HookTypeDescription
leafBatchIdsstring[]Batch IDs for each successful upload
To use hooks in React, wrap your component tree with the <Leaf> context provider: 
import { Leaf, Providers, useLeaf } from "@withleaf/leaf-link-react";

function StatusDisplay() {
  const { providerWidgetStatus, providersConnected } = useLeaf();
  return <pre>{JSON.stringify({ providerWidgetStatus, providersConnected }, null, 2)}</pre>;
}

function App() {
  return (
    <Leaf>
      <StatusDisplay />
      <Providers
        leafUser="your-leaf-user-id"
        apiKey="your-leaf-user-api-key"
        companyName="Acme Ag"
        companyLogo="https://example.com/logo.svg"
      />
    </Leaf>
  );
}
In Angular, use the (getWidgetStatus) output binding on the <providers> component.
The Angular package does not currently expose Stara in its provider list.

​
What to do next

Last modified on March 24, 2026