> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withleaf.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Leaf Users

> Leaf users are the central organizing concept in the API. Each holds provider credentials, and all fields, machine files, and field operations belong to one.

A Leaf user is the entity that holds provider credentials and owns all the data that flows from those connections. Every field, machine file, field operation, and satellite image in Leaf belongs to exactly one Leaf user. When you create a Leaf user and attach provider credentials, Leaf begins syncing data from that provider automatically.

In practice, most implementations create one Leaf user per grower, and that's the simplest way to think about it. But a Leaf user is really defined by the credentials attached to it, not by a strict 1:1 relationship with a single grower. A John Deere Operations Center account, for example, may contain data from multiple organizations and multiple growers (called "clients" in John Deere's terminology). If you connect that account to a single 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, but does not treat it as a separate entity in the hierarchy.

## 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](/components/leaf-connect).

```mermaid theme={null}
graph TD
    APIOwner["API Owner"] --> LeafUserA["Leaf User A"]
    APIOwner --> LeafUserB["Leaf User B"]
    LeafUserA --> CredsA["Provider Credentials"]
    LeafUserA --> FieldsA["Fields & Boundaries"]
    LeafUserA --> FilesA["Machine Files"]
    LeafUserA --> OpsA["Field Operations"]
    LeafUserB --> CredsB["Provider Credentials"]
    LeafUserB --> FieldsB["Fields & Boundaries"]
    LeafUserB --> FilesB["Machine Files"]
    LeafUserB --> OpsB["Field Operations"]
```

For the full terminology and data pipeline, see [Core Concepts](/getting-started/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 (the `name` 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](/providers/organizations) and [Configuration](/configuration/overview) 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.

<Note>
  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.
</Note>

## Mapping Leaf users to your own system

The `externalId` 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](/api-reference/users#get-all-leaf-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](/configuration/overview).

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](/providers/overview) for details on each provider.
* **Via Leaf widgets** -- [Magic Link](/components/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](/components/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](/configuration/overview) 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.

<Warning>
  Do not repeatedly connect the same large provider account during development. Each connection syncs data and consumes your testing acre allotment. Use `customDataSync` to limit processing to specific fields, and `organizationDataSync` set to `SELECTED_ONLY` to control which John Deere organizations Leaf processes. See [Configuration](/configuration/overview) for details on both settings.
</Warning>

## 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, set `organizationDataSync` to `SELECTED_ONLY` before connecting the account. See [Provider Organizations](/providers/organizations) for managing which organizations sync.

**Use PATCH for simple profile changes.** The partial update endpoint (`PATCH /users/{id}`) lets you change profile fields like `name`, `email`, `phone`, `address`, or `externalId` without affecting provider credentials. Only the fields you send are updated.

**PUT is a full replacement.** The full 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](/api-reference/users) -- endpoint details for creating, reading, updating (full and partial), and deleting Leaf users.
* [Connecting Providers](/providers/overview) -- how to attach provider credentials to a Leaf user.
* [Configuration](/configuration/overview) -- control how Leaf processes data, at the API owner or Leaf user level.
* [Quickstart](/getting-started/quickstart) -- walk through the full setup end to end.