Migrate from Trimble to FarmEngage

​

What changed

​

What you need before migrating

• FarmEngage API access from PTx, with a new AGCO clientId and clientSecret. Request access at PTx’s API request form. Legacy Trimble developer credentials do not work.
• Your FarmEngage application’s redirect URL registered with PTx. For Magic Link or Leaf Link, that URL is https://widget.withleaf.io.
• Each grower must re-authorize through the AGCO ID OAuth flow. Existing Trimble refresh tokens do not carry over.
• Each grower must grant your application access to their FarmEngage organizations. Authentication alone is not enough.

​

Migration approach: run both in parallel

1. Register your FarmEngage app keys with Leaf:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"clientId": "your-agco-client-id", "clientSecret": "your-agco-client-secret"}' \
  "https://api.withleaf.io/services/usermanagement/api/app-keys/FarmEngage/your-app-name"

2. For each grower you want to migrate:
   • Run the FarmEngage OAuth flow (through the Leaf helper, Magic Link, or Leaf Link). If you use a widget, create the link for the existing Leaf user (POST /magic-link/users/{leafUserId}/provider or the widget bound to that leafUserId). Do not use the create-new-user Magic Link path for cutover.
   • Attach farm-engage-credentials to the same Leaf user that already has trimble-credentials.
   • Call GET /users/{leafUserId}/organizations/FarmEngage. If connectedOrganizations is empty, send the grower the managementUri. An empty list can mean a skipped organization grant or a FarmEngage account with no organizations.
   • Verify fields and files appear with "provider": "FarmEngage". Field and file verification requires fieldsAutoSync and operationsAutoSync enabled for that API owner or Leaf user.
   • After you confirm, delete the old trimble-credentials from the Leaf user. That stops new Trimble syncs. Already-synced Trimble fields, files, and operations remain with "provider": "Trimble" and stay queryable.
3. Growers you have not migrated yet continue working on the legacy Trimble provider until you switch them — or until PTx disables that API.

​

Suggested cutover order

1. A test or QA Leaf user you control.
2. One production grower who already uses FarmEngage and can complete organization authorization with you on the call.
3. Remaining production growers, before PTx’s cutoff.

​

FarmEngage data in the API

• Legacy Trimble: "provider": "Trimble"
• FarmEngage: "provider": "FarmEngage"

curl "https://api.withleaf.io/services/integrations/api/resources?leafUserId={leafUserId}&provider=FarmEngage" \
  -H "Authorization: Bearer YOUR_TOKEN"

​

Abbreviated setup steps

1. Get the authorization URL — POST https://trimble-oauth2-helper.withleaf.io/farmengage/get_url with client_id and client_redirect_url.
2. Redirect the grower — they sign in with AGCO ID and consent.
3. Exchange the code for tokens — POST https://trimble-oauth2-helper.withleaf.io/farmengage/get_token with client_id, client_secret, redirect_url, and code. The token field name is redirect_url, not client_redirect_url.
4. Attach credentials to the Leaf user — POST /users/{leafUserId}/farm-engage-credentials with clientId, clientSecret, and refreshToken.
5. Confirm organizations — GET /users/{leafUserId}/organizations/FarmEngage. If connectedOrganizations is empty, Leaf detects no authorized FarmEngage organizations. That can be a skipped organization grant or a FarmEngage account with no organizations. Send the grower the managementUri for the grant path.
6. Confirm data — GET /users/{leafUserId}/farm-engage-credentials, then fields and files with ?provider=FarmEngage.

​

Update Magic Link and Leaf Link

1. Register your FarmEngage app keys with Leaf (see the preceding curl example).
2. Add https://widget.withleaf.io as a callback/redirect URL on your FarmEngage application with PTx.
3. Update your allowedProviders to include "FarmEngage". During the transition, you can include both "Trimble" and "FarmEngage" so growers can connect through either provider.

{
  "allowedProviders": ["Trimble", "FarmEngage"]
}

​

Common mistakes

• Posting Trimble tokens to /farm-engage-credentials. Leaf confirms by refreshing against AGCO ID, then calling FarmEngage GET /config/organizations. Trimble tokens fail that confirm step. Leaf returns HTTP 400 and does not persist the credential.
• Calling /get_url instead of /farmengage/get_url. That helper still talks to Trimble Identity.
• Sending client_redirect_url on get_token. The FarmEngage token helper requires redirect_url.
• Mixing helper and Leaf field names. The FarmEngage helper returns refresh_token. The Leaf credentials API expects refreshToken.
• Skipping organization authorization. A valid credential with zero organizations looks like a successful connect and an empty sync.
• Joining FarmEngage UUIDs to stored Trimble organization and field IDs. Remap using name or geometry, or treat FarmEngage as a new provider graph.
• Leaving both credentials attached. Expect a second field, file, and operations graph until you delete trimble-credentials. Deleting the credential does not remove already-synced Trimble-provider records.

​

What to do next

• FarmEngage provider guide — Credentials schema, endpoints, and troubleshooting.
• Connect FarmEngage tutorial — Full step-by-step with code examples.
• Provider credentials API reference — Endpoint reference for all providers.