How Leaf users fit into the hierarchy
The account structure is: API owner → Leaf users → Data. Your API owner is the top-level Leaf account, identified by an email address. Beneath it, each Leaf user acts as an isolated container. Fields, machine files, field operations, and provider credentials all live under a specific Leaf user. Data does not cross Leaf user boundaries within an API owner, though Leaf users can be shared across API owners using Leaf Connect. For the full terminology and data pipeline, see Core Concepts.Leaf users and growers
The most common pattern is one Leaf user per grower, and that’s the recommended starting point. But it’s worth understanding what happens when the provider-side account doesn’t line up neatly with a single grower. With John Deere, a single Operations Center account can span multiple organizations and multiple clients (John Deere’s term for growers). If you connect that account to one Leaf user, all of that data — across all organizations and clients — lands under that one Leaf user. Leaf tracks the provider-side grower as a property on individual files and fields (thename attribute on growers comes directly from the client name at John Deere), but does not treat it as a separate entity in the hierarchy.
You can control what actually gets synced. organizationDataSync controls which John Deere organizations Leaf processes — set it to SELECTED_ONLY to pick specific ones instead of syncing everything the account has access to. customDataSync controls which fields are fully processed versus held in preview mode. Together, these let you narrow the scope of a broad provider connection without needing to split it across multiple Leaf users. See Provider Organizations and Configuration for details.
Other providers work similarly in principle: the credentials you attach determine what data flows in, and all of it lands under the Leaf user that holds those credentials.
If your use case requires a different mapping than one Leaf user per grower (for example, one per region or per farm), talk to Customer Success before committing to an architecture. The choice affects billing, data isolation, and configuration granularity.
Mapping Leaf users to your own system
TheexternalId field on a Leaf user lets you store your own internal user ID, making it straightforward to match Leaf users back to accounts in your system. You can filter the GET /users endpoint by externalId to look up a Leaf user from your own identifier.
Connecting providers
A Leaf user can be connected to multiple providers (John Deere, Climate FieldView, CNHi, Trimble, AgLeader, etc.), but only one credential set per provider. Once credentials are attached, Leaf begins syncing data from that provider for the Leaf user — pulling field boundaries, machine files, and creating field operations based on your configurations. There are two ways to connect a grower’s provider account to a Leaf user:- Via the API — your application manages the OAuth flow with the provider and passes the resulting credentials to Leaf. See Connecting Providers for details on each provider.
- Via Leaf widgets — Magic Link is a hosted web page you send to growers; they click it and authorize their provider account without touching your API. Leaf Link is an embeddable React or Angular component that does the same thing inside your own UI.
Configuration inheritance
Configurations control how Leaf ingests, processes, and outputs data. They cascade from the API owner down to Leaf users: any setting on the API owner applies to all Leaf users unless a specific Leaf user has its own override. Configuration changes are not retroactive — they only affect data processed after the change. This means you can set sensible defaults at the API owner level (processing range, filtered GeoJSON, custom data sync) and override them selectively for specific growers. See Configuration for the full list of settings.Account structure patterns
Standard pattern: one API owner per environment (test, staging, production), one Leaf user per grower. This is the most common setup. It keeps each grower’s data isolated, maps cleanly to billing (usage is tracked per Leaf user), and lets you apply per-grower configuration overrides when needed. Managed service provider pattern: if you serve multiple client organizations, consider a separate API owner per client (per environment). Each client’s API owner holds Leaf users for that client’s growers. This gives you billing isolation between clients and lets you apply entirely different configurations per client org.Things to watch for
John Deere organization scope. John Deere accounts often have access to many organizations. By default, Leaf syncs data from all of them. If you only need a subset, setorganizationDataSync to SELECTED_ONLY before connecting the account. See Provider Organizations for managing which organizations sync.
PUT is a full replacement. The update endpoint (PUT /users) replaces the entire Leaf user object. If the existing user has provider credentials and you omit them from the request body, those credentials are removed. Always include credentials you want to keep.
Deletion is permanent. Deleting a Leaf user removes all associated provider credentials and stops data syncing. This cannot be undone.
What to do next
- Leaf Users API Reference — endpoint details for creating, reading, updating, and deleting Leaf users.
- Connecting Providers — how to attach provider credentials to a Leaf user.
- Configuration — control how Leaf processes data, at the API owner or Leaf user level.
- Quickstart — walk through the full setup end to end.