> ## 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.

# Connect to Trimble API

> Connect Trimble Agriculture data to Leaf. Register a developer application, complete the OAuth flow, and attach credentials to a Leaf user.

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.

<Tip>
  [Magic Link](/components/magic-link) and [Leaf Link](/components/leaf-link) handle the OAuth UI for you. This tutorial covers the manual flow for developers building it into their own application.
</Tip>

## Before you start

* A Leaf account with a valid API token.
* A Leaf user created.
* A Trimble developer account. Register at [agdeveloper.trimble.com](https://agdeveloper.trimble.com/log-in-or-register/).
* API credentials requested through [Trimble's integration request page](https://agriculture.trimble.com/en/partners/developer-resources/request-software-integration-api). 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:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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"]
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

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

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](/providers/organizations).

After authorization, Trimble redirects to your `client_redirect_url` with a `code` parameter.

## Step 2: Exchange the code for tokens

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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"]
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

## Step 3: Attach credentials to the Leaf user

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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());
  ```
</CodeGroup>

Leaf handles token refresh automatically after this point.

## Step 4: Confirm the credentials are attached

```bash theme={null}
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](/guides/tutorials/field-operations-quickstart) endpoints.

For the credentials schema and management endpoints, see the [Trimble provider guide](/providers/trimble) and the [provider credentials API reference](/api-reference/providers).