Trimble

PTx/AGCO is retiring the Trimble Agriculture API. For a new integration, use FarmEngage. Existing Trimble connections continue to work until PTx turns off that API. To move existing connections, see Migrate from Trimble to FarmEngage.

Leaf connects to Trimble Agriculture using OAuth 2.0. Once connected, Leaf syncs growers, farms, fields, machine files, and field operations for the Leaf user.

Prerequisites

A Trimble Agriculture developer account. Register here.
Your application’s clientId and clientSecret from Trimble.
A grower’s refreshToken obtained through the Trimble OAuth 2.0 consent flow.

Setup steps

Complete the Trimble OAuth 2.0 flow to obtain a refreshToken for the grower’s account.
POST the credentials to Leaf:

curl -X POST \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "refreshToken": "grower-refresh-token"
    }' \
    'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/trimble-credentials'

import requests

TOKEN = 'YOUR_TOKEN'

endpoint = 'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/trimble-credentials'
headers = {'Authorization': f'Bearer {TOKEN}'}

data = {
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "refreshToken": "grower-refresh-token"
}

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/users/{leafUserId}/trimble-credentials'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

const data = {
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "refreshToken": "grower-refresh-token"
}

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

Leaf validates the token and begins syncing. Check credential status with GET /users/{leafUserId}/trimble-credentials.

Credentials schema

Create request body:

Field	Type	Required	Description
`clientId`	string	Yes	Your application’s client ID from Trimble
`clientSecret`	string	Yes	Your application’s client secret
`refreshToken`	string	Yes	The grower’s OAuth refresh token

Response:

{
  "id": "uuid",
  "status": "str",
  "createdTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'",
  "tokenMetadata": {"scopes": ["str"]},
  "clientId": "str",
  "clientSecret": "str",
  "accessToken": "str",
  "refreshToken": "str"
}

Endpoints

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

Action	Method	Path
Get credentials	GET	`/users/{leafUserId}/trimble-credentials`
Create credentials	POST	`/users/{leafUserId}/trimble-credentials`
Delete credentials	DELETE	`/users/{leafUserId}/trimble-credentials`
Get credential events	GET	`/users/{leafUserId}/trimble-credentials/events`

Troubleshooting

Use the events endpoint to inspect credential health:

curl -X GET \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/trimble-credentials/events'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/trimble-credentials/events'
headers = {'Authorization': f'Bearer {TOKEN}'}

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

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/trimble-credentials/events'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
    .then(res => console.log(res.data))
    .catch(console.error)

Event logs are retained for 30 days. Once the credential is deleted or disassociated from the Leaf user, the logs are no longer available.

Common issues:

Status changes to invalid: The grower may have revoked access or the refresh token expired. Have the grower re-authorize through Trimble’s OAuth flow.

What to do next

Connect Trimble Tutorial — Step-by-step walkthrough for the legacy API.
FarmEngage — The PTx/AGCO provider that replaces Trimble.
Migrate from Trimble to FarmEngage — Move existing Trimble connections to FarmEngage.
Provider Authentication Overview — How provider credentials work across all providers.
API Reference: Providers — Full endpoint reference for provider credentials.

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

Prerequisites

Setup steps

Credentials schema

Endpoints

Troubleshooting

What to do next

​Prerequisites

​Setup steps

​Credentials schema

​Endpoints

​Troubleshooting

​What to do next

Prerequisites

Setup steps

Credentials schema

Endpoints

Troubleshooting

What to do next