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

# Stara

> Connect to Stara Telemetry to pull machine files and field operations through Leaf's provider credentials API.

Leaf connects to Stara using an API key combined with OAuth tokens. Once connected, Leaf syncs fields, machine files, and field operations. Stara's FMIS structure exposes fields only (no separate grower or farm hierarchy).

## Prerequisites

1. A Stara developer/partner account with API access.
2. Your `apiKey` from Stara.
3. The grower's `accessToken`, `accessTokenClient`, and `refreshToken` from the Stara authentication flow.

## 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",
        "accessToken": "grower-access-token",
        "accessTokenClient": "grower-access-token-client",
        "refreshToken": "grower-refresh-token"
      }' \
      'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/stara-credentials'
  ```

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

  TOKEN = 'YOUR_TOKEN'

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

  data = {
      "apiKey": "your-api-key",
      "accessToken": "grower-access-token",
      "accessTokenClient": "grower-access-token-client",
      "refreshToken": "grower-refresh-token"
  }

  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}/stara-credentials'
  const headers = { 'Authorization': `Bearer ${TOKEN}` }

  const data = {
      "apiKey": "your-api-key",
      "accessToken": "grower-access-token",
      "accessTokenClient": "grower-access-token-client",
      "refreshToken": "grower-refresh-token"
  }

  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 Stara API key               |
| `accessToken`       | string | Yes      | The grower's access token        |
| `accessTokenClient` | string | Yes      | The grower's client access token |
| `refreshToken`      | string | Yes      | The grower's refresh token       |

**Response:**

```json theme={null}
{
  "id": "uuid",
  "status": "str",
  "createdTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'",
  "accessTokenClient": "str",
  "refreshToken": "str",
  "accessToken": "str",
  "apiKey": "str"
}
```

## Endpoints

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

| Action                | Method | Path                                           |
| --------------------- | ------ | ---------------------------------------------- |
| Get credentials       | GET    | `/users/{leafUserId}/stara-credentials`        |
| Create credentials    | POST   | `/users/{leafUserId}/stara-credentials`        |
| Delete credentials    | DELETE | `/users/{leafUserId}/stara-credentials`        |
| Get credential events | GET    | `/users/{leafUserId}/stara-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}/stara-credentials/events'
  ```

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

  TOKEN = 'YOUR_TOKEN'
  endpoint = 'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/stara-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}/stara-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:

* **No grower/farm hierarchy**: Stara only exposes fields. If you expect grower or farm-level data, it won't be available from this provider.
* **Status changes to invalid**: Tokens may have expired. Re-authenticate the grower through Stara.

## What to do next

* [Connect Stara Tutorial](/guides/tutorials/connect-stara) — Step-by-step walkthrough.
* [Provider Authentication Overview](/providers/overview) — How provider credentials work across all providers.
* [API Reference: Providers](/api-reference/providers) — Full endpoint reference for provider credentials.