Leaf Link

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, CNHI FieldOps, 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

A Leaf account with at least one Leaf user created.
A Leaf user API key (created via POST /api-keys).
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.

Provider	Redirect URL field	Credentials needed
John Deere	Redirect URI	`clientKey`, `clientSecret`
Climate FieldView	(none required)	`apiKey`, `clientId`, `clientSecret`
CNHI (AFS Connect - Legacy)	App OAuth Callback URL(s)	`clientId`, `clientSecret`, `subscriptionKey`
CNHI FieldOps	App OAuth Callback URL(s)	`clientId`, `clientSecret`, `subscriptionKey`
AgLeader	Redirection URL	`privateKey`, `publicKey`
Trimble	Authentication Callback URL	`applicationName`, `clientId`, `clientSecret`
Raven Slingshot	(none required)	`apiKey`, `sharedSecret`
Lindsay	Redirect URI	`clientId`, `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'

import requests

TOKEN = "YOUR_TOKEN"
endpoint = "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/MyApp/PRODUCTION"
headers = {"Authorization": f"Bearer {TOKEN}"}
data = {"clientKey": "your-app-id", "clientSecret": "your-secret"}

response = requests.post(endpoint, headers=headers, json=data)
print(response.json())

const axios = require("axios");

const TOKEN = "YOUR_TOKEN";
const endpoint = "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/MyApp/PRODUCTION";
const headers = { Authorization: `Bearer ${TOKEN}` };
const data = { clientKey: "your-app-id", clientSecret: "your-secret" };

axios.post(endpoint, data, { headers }).then(res => console.log(res.data));

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

Property	Type	Description
`apiKey`	String	Leaf user API key (required)
`leafUser`	String	Leaf user ID (required)
`companyName`	String	Your company name, displayed in the widget
`companyLogo`	String	URL to your company logo (PNG, JPEG, or SVG)
`isDarkMode`	Boolean	Enable dark mode. Default: `false`
`locale`	String	Force language: `en_US`, `pt_BR`, `es_ES`, or `fr_FR`. Defaults to browser language
`title`	String	Widget title. Default: “Select your integration”
`showSearchbar`	Boolean	Show/hide the provider search bar. Default: `true`
`allowedProviders`	`string[]`	Restrict the widget to a specific list of providers
`fastMode`	Boolean	Enable the widget’s fast mode behavior
`applications`	`Array<{ appName: string; provider: string; clientEnvironment: string }>`	Preload provider app settings for the widget

File Upload

Property	Type	Description
`apiKey`	String	Leaf user API key (required)
`leafUser`	String	Leaf user ID (required)
`companyName`	String	Your company name
`companyLogo`	String	URL to your company logo
`isDarkMode`	Boolean	Enable dark mode. Default: `false`
`locale`	String	Force language
`title`	String	Text displayed at the top of the widget
`filesTimeRange`	Number	Days 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:

Hook	Type	Description
`providersConnected`	`string[]`	Provider names connected after the flow completes
`providerWidgetStatus`	`{ code: number; message: string }`	Widget status: `-1` Error, `0` Started, `1` Done

File Upload hooks

Hook	Type	Description
`leafBatchIds`	`string[]`	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

Magic Link for generating shareable authentication and upload links without embedding widgets.
Leaf Connect for sharing data between API owners.
Leaf Link API Reference for API key and app info endpoints.

Getting Started

Configuration

Alerts

Leaf Users

Connecting Providers

Data Hierarchy

Machine Data

Satellite Imagery

Weather

Soil Sampling

Leaf Lake

UI Components

MCP Server

Irrigation

Beta

Administration

Widgets

Prerequisites

Provider setup

Installation

React

Angular

Properties

Provider Connection

File Upload

Hooks

Provider Connection hooks

File Upload hooks

What to do next

​Widgets

​Prerequisites

​Provider setup

​Installation

​React

​Angular

​Properties

​Provider Connection

​File Upload

​Hooks

​Provider Connection hooks

​File Upload hooks

​What to do next

Widgets

Prerequisites

Provider setup

Installation

React

Angular

Properties

Provider Connection

File Upload

Hooks

Provider Connection hooks

File Upload hooks

What to do next