Leaf Link

Use the Leaf Link endpoints to create API keys for widget sessions and to register provider application credentials for embedded OAuth flows. This page is the reference for the backend setup that powers the Leaf Link UI components. For conceptual background, see Leaf Link.

Overview

Leaf Link widgets let your users connect their provider accounts directly from your application. To use them, you need:

An API key scoped to a Leaf user for widget authentication.
Provider app registrations so Leaf knows which provider credentials to use during the OAuth flow.

Base URL: https://api.withleaf.io/services/usermanagement/api

API Keys

API keys authenticate Leaf Link widget sessions for a specific Leaf user.

Endpoints

Endpoint	Method	Path
Get all API keys	`GET`	`/api-keys`
Create an API key	`POST`	`/api-keys`
Revoke an API key	`DELETE`	`/api-keys/{apiKeyId}`

Get all API keys

GET /api-keys Returns every API key associated with a Leaf user.

Parameters

Parameter	Type	Required	Description
`leafUserId`	string	Yes	The UUID of the Leaf user to query keys for.

curl -X GET \
  "https://api.withleaf.io/services/usermanagement/api/api-keys?leafUserId={leafUserId}" \
  -H "Authorization: Bearer {token}"

import requests

url = "https://api.withleaf.io/services/usermanagement/api/api-keys"
headers = {"Authorization": f"Bearer {token}"}
params = {"leafUserId": leaf_user_id}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const response = await fetch(
  `https://api.withleaf.io/services/usermanagement/api/api-keys?leafUserId=${leafUserId}`,
  { headers: { Authorization: `Bearer ${token}` } }
);
const keys = await response.json();

Response

[
  {
    "key": "lk_abc123...",
    "expiresAt": "2025-10-01T00:00:00.000Z",
    "valid": true
  }
]

Create an API key

POST /api-keys Creates a new API key for widget authentication.

Request body

Field	Type	Required	Description
`leafUserId`	string	Yes	The UUID of the Leaf user.
`expiresIn`	integer	No	Lifetime in seconds. Minimum `900`. Defaults to 1 year.
`description`	string	No	A human-readable label for the key.

curl -X POST \
  "https://api.withleaf.io/services/usermanagement/api/api-keys" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "leafUserId": "{leafUserId}",
    "expiresIn": 86400,
    "description": "Production widget key"
  }'

import requests

url = "https://api.withleaf.io/services/usermanagement/api/api-keys"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}
body = {
    "leafUserId": leaf_user_id,
    "expiresIn": 86400,
    "description": "Production widget key",
}

response = requests.post(url, headers=headers, json=body)
print(response.json())

const response = await fetch(
  "https://api.withleaf.io/services/usermanagement/api/api-keys",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      leafUserId,
      expiresIn: 86400,
      description: "Production widget key",
    }),
  }
);
const key = await response.json();

Response

{
  "key": "lk_abc123...",
  "expiresAt": "2025-10-02T00:00:00.000Z",
  "valid": true
}

Revoke an API key

DELETE /api-keys/{apiKeyId} Permanently revokes an API key. This action cannot be undone.

Path parameters

Parameter	Type	Required	Description
`apiKeyId`	string	Yes	The ID of the key to revoke.

curl -X DELETE \
  "https://api.withleaf.io/services/usermanagement/api/api-keys/{apiKeyId}" \
  -H "Authorization: Bearer {token}"

import requests

url = f"https://api.withleaf.io/services/usermanagement/api/api-keys/{api_key_id}"
headers = {"Authorization": f"Bearer {token}"}

response = requests.delete(url, headers=headers)

await fetch(
  `https://api.withleaf.io/services/usermanagement/api/api-keys/${apiKeyId}`,
  {
    method: "DELETE",
    headers: { Authorization: `Bearer ${token}` },
  }
);

Provider App Information

Register your provider application credentials so Leaf Link widgets can initiate the OAuth flow on behalf of your users. All providers support the same CRUD operations, but the path shape differs depending on whether the provider uses a clientEnvironment.

Endpoint pattern

Providers without clientEnvironment use this pattern:

Endpoint	Method	Path
Get all apps	`GET`	`/app-keys/{Provider}`
Get an app by name	`GET`	`/app-keys/{Provider}/{appName}`
Create an app	`POST`	`/app-keys/{Provider}/{appName}`
Update an app	`PUT`	`/app-keys/{Provider}/{appName}`
Delete an app	`DELETE`	`/app-keys/{Provider}/{appName}`

For CNHI, CNHI FieldOps, and John Deere, the provider-specific endpoint pattern is:

GET /app-keys/{Provider}
GET /app-keys/{Provider}/{appName}/{clientEnvironment}
POST /app-keys/{Provider}/{appName}/{clientEnvironment}
PUT /app-keys/{Provider}/{appName}/{clientEnvironment}
DELETE /app-keys/{Provider}/{appName}/{clientEnvironment}

The client environment is typically STAGE or PRODUCTION.

Supported providers and request body fields

Provider	Path segment	Request body fields
AgLeader	`AgLeader`	`privateKey`, `publicKey`
Climate FieldView	`ClimateFieldView`	`apiKey`, `clientId`, `clientSecret`
CNHI (AFS Connect - Legacy)	`CNHI`	`clientId`, `clientSecret`, `subscriptionKey`
CNHI FieldOps	`CNHIFieldOps`	`clientId`, `clientSecret`, `subscriptionKey`
John Deere	`JohnDeere`	`clientKey`, `clientSecret`
Trimble	`Trimble`	`applicationName`, `clientId`, `clientSecret`
Raven Slingshot	`RavenSlingshot`	`apiKey`, `sharedSecret`
Stara	`Stara`	`user`, `pwd`

CNHI, John Deere, and Trimble require you to register https://widget.withleaf.io as a callback/redirect URL in your provider developer portal before Leaf Link can complete the OAuth flow.

Example: John Deere

The examples below show the full CRUD lifecycle for John Deere. All other providers follow the same pattern — only the path segment and request body fields differ.

Create a John Deere app

POST /app-keys/JohnDeere/{appName}/{clientEnvironment}

curl -X POST \
  "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/my-jd-app/PRODUCTION" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "{clientKey}",
    "clientSecret": "{clientSecret}"
  }'

import requests

url = "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/my-jd-app/PRODUCTION"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}
body = {
    "clientKey": client_key,
    "clientSecret": client_secret,
}

response = requests.post(url, headers=headers, json=body)
print(response.json())

const response = await fetch(
  "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/my-jd-app/PRODUCTION",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      clientKey,
      clientSecret,
    }),
  }
);
const app = await response.json();

Get all John Deere apps

GET /app-keys/JohnDeere

curl -X GET \
  "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere" \
  -H "Authorization: Bearer {token}"

import requests

url = "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere"
headers = {"Authorization": f"Bearer {token}"}

response = requests.get(url, headers=headers)
print(response.json())

const response = await fetch(
  "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere",
  { headers: { Authorization: `Bearer ${token}` } }
);
const apps = await response.json();

Get a John Deere app by name

GET /app-keys/JohnDeere/{appName}/{clientEnvironment}

curl -X GET \
  "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/my-jd-app/PRODUCTION" \
  -H "Authorization: Bearer {token}"

import requests

url = "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/my-jd-app/PRODUCTION"
headers = {"Authorization": f"Bearer {token}"}

response = requests.get(url, headers=headers)
print(response.json())

const response = await fetch(
  "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/my-jd-app/PRODUCTION",
  { headers: { Authorization: `Bearer ${token}` } }
);
const app = await response.json();

Update a John Deere app

PUT /app-keys/JohnDeere/{appName}/{clientEnvironment}

curl -X PUT \
  "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/my-jd-app/PRODUCTION" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "{newClientKey}",
    "clientSecret": "{newClientSecret}"
  }'

import requests

url = "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/my-jd-app/PRODUCTION"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}
body = {
    "clientKey": new_client_key,
    "clientSecret": new_client_secret,
}

response = requests.put(url, headers=headers, json=body)
print(response.json())

const response = await fetch(
  "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/my-jd-app/PRODUCTION",
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      clientKey: newClientKey,
      clientSecret: newClientSecret,
    }),
  }
);
const updated = await response.json();

Delete a John Deere app

DELETE /app-keys/JohnDeere/{appName}/{clientEnvironment}

curl -X DELETE \
  "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/my-jd-app/PRODUCTION" \
  -H "Authorization: Bearer {token}"

import requests

url = "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/my-jd-app/PRODUCTION"
headers = {"Authorization": f"Bearer {token}"}

response = requests.delete(url, headers=headers)

await fetch(
  "https://api.withleaf.io/services/usermanagement/api/app-keys/JohnDeere/my-jd-app/PRODUCTION",
  {
    method: "DELETE",
    headers: { Authorization: `Bearer ${token}` },
  }
);

Use the provider path matrix above when adapting these examples. Providers without clientEnvironment keep appName in the path, but omit the trailing environment segment.

Authentication

Configuration

Leaf Users

Alerts

Providers

Data Hierarchy

Machine data

Satellite imagery

Weather

Soil Sampling

Leaf Lake

UI components

MCP server

Irrigation

Usage tracking

Beta

Overview

API Keys

Endpoints

Get all API keys

Parameters

Response

Create an API key

Request body

Response

Revoke an API key

Path parameters

Provider App Information

Endpoint pattern

Supported providers and request body fields

Example: John Deere

Create a John Deere app

Get all John Deere apps

Get a John Deere app by name

Update a John Deere app

Delete a John Deere app

​Overview

​API Keys

​Endpoints

​Get all API keys

​Parameters

​Response

​Create an API key

​Request body

​Response

​Revoke an API key

​Path parameters

​Provider App Information

​Endpoint pattern

​Supported providers and request body fields

​Example: John Deere

​Create a John Deere app

​Get all John Deere apps

​Get a John Deere app by name

​Update a John Deere app

​Delete a John Deere app

Overview

API Keys

Endpoints

Get all API keys

Parameters

Response

Create an API key

Request body

Response

Revoke an API key

Path parameters

Provider App Information

Endpoint pattern

Supported providers and request body fields

Example: John Deere

Create a John Deere app

Get all John Deere apps

Get a John Deere app by name

Update a John Deere app

Delete a John Deere app