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}"
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"
}'
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}"
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 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 | CNHI | 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}"
}'
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}"
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}"
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}"
}'
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}"
Use the provider path matrix above when adapting these examples. Providers without clientEnvironment keep appName in the path, but omit the trailing environment segment.
