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

# Raven

> Connect to Raven using OAuth 2.0 to pull grower, farm, and field data through Leaf's provider credentials API.

Leaf connects to Raven using OAuth 2.0 credentials. Once connected, Leaf syncs grower, farm, and field data for the Leaf user.

This is separate from [Raven Slingshot](/providers/raven-slingshot), which uses API key credentials for machine file ingestion.

## Prerequisites

1. A Raven developer account with OAuth application credentials.
2. Your application's `clientId` and `clientSecret` from Raven.
3. A grower's `refreshToken` obtained through the Raven OAuth 2.0 consent flow.

## Credentials schema

| Field          | Type   | Required | Description                           |
| -------------- | ------ | -------- | ------------------------------------- |
| `clientId`     | string | Yes      | Your Raven application client ID.     |
| `clientSecret` | string | Yes      | Your Raven application client secret. |
| `refreshToken` | string | Yes      | The grower's OAuth refresh token.     |

## Endpoints

| Method | Path                                           | Description                                |
| ------ | ---------------------------------------------- | ------------------------------------------ |
| GET    | `/users/{leafUserId}/raven-credentials`        | Get stored credentials.                    |
| POST   | `/users/{leafUserId}/raven-credentials`        | Create credentials.                        |
| DELETE | `/users/{leafUserId}/raven-credentials`        | Delete credentials.                        |
| GET    | `/users/{leafUserId}/raven-credentials/events` | Get credential events for troubleshooting. |

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

### Create credentials

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "refreshToken": "grower-refresh-token"
    }' \
    'https://api.withleaf.io/services/usermanagement/api/users/{leafUserId}/raven-credentials'
  ```

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

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

  payload = {
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "refreshToken": "grower-refresh-token",
  }

  response = requests.post(endpoint, headers=headers, json=payload)
  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}/raven-credentials";
  const headers = { Authorization: `Bearer ${TOKEN}` };

  const payload = {
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
    refreshToken: "grower-refresh-token",
  };

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

### Response

```json theme={null}
{
  "id": "uuid",
  "status": "str",
  "createdTime": "2026-01-15T12:00:00.000000Z",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "accessToken": "str",
  "refreshToken": "grower-refresh-token"
}
```

## Troubleshooting

Use the events endpoint to check credential health. Events are retained for 30 days and are deleted when the credential is removed.

```
GET /users/{leafUserId}/raven-credentials/events
```

## What to do next

* [Raven Slingshot](/providers/raven-slingshot) for API key-based machine file ingestion.
* [API Reference: Providers](/api-reference/providers) for the full credential path matrix.