Leaf connects to agricultural data providers on behalf of your users. You store provider credentials on a Leaf user, and Leaf handles token refresh, data synchronization, and retry logic from that point forward.
How it works
Each provider requires its own set of credentials, typically obtained through an OAuth 2.0 flow that your application manages or that Leaf’s Magic Link widget handles for you.
The general sequence:
- Register as a developer/partner with the provider and receive your app-level credentials (client ID, client secret, API keys, etc.).
- Guide the grower through the provider’s OAuth consent flow to obtain a refresh token.
- POST those credentials to the appropriate Leaf endpoint for the Leaf user:
/users/{leafUserId}/{provider}-credentials.
- Leaf validates the credentials, begins syncing fields and machine files, and keeps the token refreshed automatically.
All provider credential endpoints live under the User Management service:
https://api.withleaf.io/services/usermanagement/api
| Action | Method | Path |
|---|
| Get credentials | GET | /users/{leafUserId}/{provider}-credentials |
| Create credentials | POST | /users/{leafUserId}/{provider}-credentials |
| Delete credentials | DELETE | /users/{leafUserId}/{provider}-credentials |
Authentication patterns
Most providers use OAuth 2.0 with a refresh token. You complete the OAuth flow on your side (or use Magic Link) and pass the resulting tokens to Leaf. Leaf exchanges and refreshes tokens as needed.
Some providers use API key authentication instead of OAuth. Sentera uses username/password. Raven Slingshot uses an API key with access key and shared secret. The credential schema for each provider is documented on its respective page.
Environments
Several providers offer sandbox or staging environments alongside production. John Deere, CNHi, Agvance, and Precision Planting Panorama support a clientEnvironment field that accepts STAGE or PRODUCTION. Set this when creating credentials.
Leaf does not provide a separate test environment. Use distinct API owners (e.g., leaf-test@company.com vs. leaf-production@company.com) to separate test and production activity. Testing against large accounts without using customDataSync can consume acre allotments quickly.
What happens after connection
Once credentials are attached to a Leaf user:
- Leaf syncs the provider’s field structure (growers, farms, fields) based on your
fieldsAutoSync configuration.
- Machine files are fetched and converted to Leaf’s standard canonical format (available as GeoJSON or GeoParquet).
- Field operations are created by spatially allocating machine file data against field boundaries.
- Subsequent syncs run at least every 24 hours. Providers with event-driven APIs (like John Deere) trigger syncs sooner.
You can monitor credential health using the events endpoint available for each provider: GET /users/{leafUserId}/{provider}-credentials/events. Event logs are retained for 30 days.
Connecting via Magic Link
If you don’t want to build the OAuth flow yourself, Leaf provides Magic Link and Leaf Link widgets. These handle the provider consent flow and credential storage automatically. You register your provider app keys with Leaf’s /app-keys/ endpoints, then generate a link or embed the widget.
See the Magic Link documentation for setup details.
Supported providers
| Provider | Auth type | Environments | Credential endpoint suffix |
|---|
| John Deere | OAuth 2.0 | STAGE, PRODUCTION | john-deere-credentials |
| CLAAS | OAuth 2.0 | STAGE, PRODUCTION | claas-credentials |
| Climate FieldView | OAuth 2.0 | Production only | climate-field-view-credentials |
| CNHi | OAuth 2.0 | STAGE, PRODUCTION | cnhi-credentials |
| Trimble | OAuth 2.0 | Production only | trimble-credentials |
| AgLeader | OAuth 2.0 | Production only | ag-leader-credentials |
| Raven | OAuth 2.0 | Production only | raven-credentials |
| Raven Slingshot | API key | Production only | raven-slingshot-credentials |
| Stara | API key + OAuth | Production only | stara-credentials |
| Sentera | Username/password | Production only | sentera-credentials |
| Agvance | API key + credentials | STAGE, PRODUCTION | agvance-credentials |
| Panorama | OAuth 2.0 (Cognito) | STAGE, PRODUCTION | panorama-credentials |
Common use cases
- Multi-provider ingestion: Connect a grower’s John Deere Operations Center, Climate FieldView, CNHi, and other accounts to a single Leaf user and receive all their data in one standard format.
- Grower onboarding: Use Magic Link to let growers connect their own provider accounts without your app handling OAuth flows directly.
- Credential monitoring: Subscribe to credential alert events to detect token expirations or revoked access before it affects data flow.
- Organization scoping: For John Deere accounts with many organizations, use
organizationDataSync to limit which organizations Leaf processes.
What to do next
- Set up credentials for your first provider. We recommend starting with John Deere or Climate FieldView as they are the most common.
- Configure alerts to receive notifications when credentials change status.
- Review organizations if you need to control which provider organizations sync data.
- API Reference: Providers — Full endpoint reference for provider credentials.
