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

# Agvance

> Connect to SSI Agvance to pull field boundaries, grower data, and farm structure through Leaf's provider credentials API.

Leaf connects to Agvance using an API key combined with username/password credentials. Once connected, Leaf syncs growers, farms, and fields from the Agvance system.

## Prerequisites

1. Access to an Agvance instance with API access enabled.
2. Your `apiKey` from Agvance.
3. The `username`, `password`, and `databaseId` for the target Agvance database.
4. Optional: `clientEnvironment` if you need to override the default environment.

## Setup steps

POST the credentials to Leaf:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
      -H 'Authorization: Bearer YOUR_TOKEN' \
      -H 'Content-Type: application/json' \
      -d '{
        "apiKey": "your-api-key",
        "clientEnvironment": "PRODUCTION",
        "databaseId": "target-database-id",
        "password": "your-password",
        "username": "your-username"
      }' \
      'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/agvance-credentials'
  ```

  ```python Python theme={null}
  import requests

  TOKEN = 'YOUR_TOKEN'

  endpoint = 'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/agvance-credentials'
  headers = {'Authorization': f'Bearer {TOKEN}'}

  data = {
      "apiKey": "your-api-key",
      "clientEnvironment": "PRODUCTION",
      "databaseId": "target-database-id",
      "password": "your-password",
      "username": "your-username"
  }

  response = requests.post(endpoint, headers=headers, json=data)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios')
  const TOKEN = 'YOUR_TOKEN'

  const endpoint = 'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/agvance-credentials'
  const headers = { 'Authorization': `Bearer ${TOKEN}` }

  const data = {
      "apiKey": "your-api-key",
      "clientEnvironment": "PRODUCTION",
      "databaseId": "target-database-id",
      "password": "your-password",
      "username": "your-username"
  }

  axios.post(endpoint, data, { headers })
      .then(res => console.log(res.data))
      .catch(console.error)
  ```
</CodeGroup>

## Credentials schema

**Create request body:**

| Field               | Type   | Required | Description                                              |
| ------------------- | ------ | -------- | -------------------------------------------------------- |
| `apiKey`            | string | Yes      | Your Agvance API key                                     |
| `clientEnvironment` | string | No       | `STAGE` or `PRODUCTION`. Defaults to `STAGE` if omitted. |
| `databaseId`        | string | Yes      | The target Agvance database ID                           |
| `username`          | string | Yes      | Agvance username                                         |
| `password`          | string | Yes      | Agvance password                                         |

**Response:**

```json theme={null}
{
  "id": "uuid",
  "status": "str",
  "createdTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'",
  "clientEnvironment": "PRODUCTION",
  "username": "str",
  "password": "str",
  "databaseId": "str",
  "sessionId": "str",
  "apiKey": "str"
}
```

Leaf generates a `sessionId` after successful authentication. If you omit `clientEnvironment`, Leaf defaults it to `STAGE`.

## Confirm the credentials are attached

Check the stored credentials for the Leaf user:

```bash theme={null}
curl "https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/agvance-credentials" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

If this worked, Leaf returns the Agvance credential object with the resolved `sessionId`.

## Endpoints

Base URL: `https://api.withleaf.io/services/usermanagement/api`

| Action                | Method | Path                                             |
| --------------------- | ------ | ------------------------------------------------ |
| Get credentials       | GET    | `/users/{leafUserId}/agvance-credentials`        |
| Create credentials    | POST   | `/users/{leafUserId}/agvance-credentials`        |
| Delete credentials    | DELETE | `/users/{leafUserId}/agvance-credentials`        |
| Get credential events | GET    | `/users/{leafUserId}/agvance-credentials/events` |

## Troubleshooting

Use the events endpoint to inspect credential health:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
      -H 'Authorization: Bearer YOUR_TOKEN' \
      'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/agvance-credentials/events'
  ```

  ```python Python theme={null}
  import requests

  TOKEN = 'YOUR_TOKEN'
  endpoint = 'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/agvance-credentials/events'
  headers = {'Authorization': f'Bearer {TOKEN}'}

  response = requests.get(endpoint, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios')
  const TOKEN = 'YOUR_TOKEN'

  const endpoint = 'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/agvance-credentials/events'
  const headers = { 'Authorization': `Bearer ${TOKEN}` }

  axios.get(endpoint, { headers })
      .then(res => console.log(res.data))
      .catch(console.error)
  ```
</CodeGroup>

<Warning>
  Event logs are retained for 30 days. Once the credential is deleted or disassociated from the Leaf user, the logs are no longer available.
</Warning>

Common issues:

* **Invalid credentials**: If the password changes in Agvance, delete and recreate the credentials with the new password.
* **Wrong database ID**: Verify the `databaseId` matches the target Agvance database.
* **STAGE vs. PRODUCTION mismatch**: If you set `clientEnvironment` explicitly, make sure it matches the Agvance instance you're connecting to.

## What to do next

* [Growers](/fields/growers) for how Agvance grower and farm data appears in Leaf.
* [Fields Overview](/fields/overview) for the synced resource hierarchy.
* [Provider Credentials API Reference](/api-reference/providers) for the credential path matrix.