Connect to Trimble API

This tutorial walks through connecting Trimble Agriculture to Leaf so you can sync field boundaries, machine files, and field operations. You’ll register a developer application, run the OAuth flow, and attach the resulting provider credentials to a Leaf user.

Magic Link and Leaf Link handle the OAuth UI for you. This tutorial covers the manual flow for developers building it into their own application.

Before you start

A Leaf account with a valid API token.
A Leaf user created.
A Trimble developer account. Register at agdeveloper.trimble.com.
API credentials requested through Trimble’s integration request page. Trimble sends you a Client ID and Client Secret after approval.

Step 1: Get the authorization URL

Leaf constructs the Trimble OAuth URL for you:

curl -X POST "https://trimble-oauth2-helper.withleaf.io/get_url" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-trimble-client-id",
    "client_secret": "your-trimble-client-secret",
    "client_redirect_url": "https://your-app.com/callback"
  }'

import requests

response = requests.post(
    "https://trimble-oauth2-helper.withleaf.io/get_url",
    json={
        "client_id": "your-trimble-client-id",
        "client_secret": "your-trimble-client-secret",
        "client_redirect_url": "https://your-app.com/callback"
    }
)
auth_url = response.json()["url"]

const res = await fetch("https://trimble-oauth2-helper.withleaf.io/get_url", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: "your-trimble-client-id",
    client_secret: "your-trimble-client-secret",
    client_redirect_url: "https://your-app.com/callback",
  }),
});
const { url } = await res.json();

The redirect URL must match what Trimble authorized during your application registration in Step 1. Trailing slashes can cause failures.

Redirect the grower to the returned URL. After authentication, Trimble asks the grower to grant access to their organizations. If the grower skips this step, Leaf won’t receive data from those organizations. You can ask them to manage access later through provider organizations. After authorization, Trimble redirects to your client_redirect_url with a code parameter.

Step 2: Exchange the code for tokens

curl -X POST "https://trimble-oauth2-helper.withleaf.io/get_token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-trimble-client-id",
    "client_secret": "your-trimble-client-secret",
    "code": "the-code-from-redirect",
    "client_redirect_url": "https://your-app.com/callback"
  }'

tokens = requests.post(
    "https://trimble-oauth2-helper.withleaf.io/get_token",
    json={
        "client_id": "your-trimble-client-id",
        "client_secret": "your-trimble-client-secret",
        "code": "the-code-from-redirect",
        "client_redirect_url": "https://your-app.com/callback"
    }
).json()
access_token = tokens["accessToken"]
refresh_token = tokens["refreshToken"]

const tokenRes = await fetch(
  "https://trimble-oauth2-helper.withleaf.io/get_token",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      client_id: "your-trimble-client-id",
      client_secret: "your-trimble-client-secret",
      code: "the-code-from-redirect",
      client_redirect_url: "https://your-app.com/callback",
    }),
  }
);
const { accessToken, refreshToken } = await tokenRes.json();

Step 3: Attach credentials to the Leaf user

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

response = requests.post(
    f"https://api.withleaf.io/services/usermanagement/api/users/{leaf_user_id}/trimble-credentials",
    headers={"Authorization": f"Bearer {leaf_token}"},
    json={
        "clientId": "your-trimble-client-id",
        "clientSecret": "your-trimble-client-secret",
        "accessToken": access_token,
        "refreshToken": refresh_token
    }
)
print(response.json())

const res = await fetch(
  `https://api.withleaf.io/services/usermanagement/api/users/${leafUserId}/trimble-credentials`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${leafToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      clientId: "your-trimble-client-id",
      clientSecret: "your-trimble-client-secret",
      accessToken: accessToken,
      refreshToken: refreshToken,
    }),
  }
);
console.log(await res.json());

Leaf handles token refresh automatically after this point.

Step 4: Confirm the credentials are attached

curl "https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/trimble-credentials" \
  -H "Authorization: Bearer YOUR_LEAF_TOKEN"

If this worked, Leaf returns the Trimble credential object for the Leaf user.

What you built

You connected Trimble Agriculture to a Leaf user. Leaf now syncs field boundaries, machine files, and field operations from Trimble. Query the data through the field operations endpoints. For the credentials schema and management endpoints, see the Trimble provider guide and the provider credentials API reference.

By Use Case

AI and Agents

Tutorials

Before you start

Step 1: Get the authorization URL

Step 2: Exchange the code for tokens

Step 3: Attach credentials to the Leaf user

Step 4: Confirm the credentials are attached

What you built

​Before you start

​Step 1: Get the authorization URL

​Step 2: Exchange the code for tokens

​Step 3: Attach credentials to the Leaf user

​Step 4: Confirm the credentials are attached

​What you built

Before you start

Step 1: Get the authorization URL

Step 2: Exchange the code for tokens

Step 3: Attach credentials to the Leaf user

Step 4: Confirm the credentials are attached

What you built