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

# Connection Health

> The Connection Health feature provides a high-level view of connection stability by evaluating the status of the most recent job run. It helps identify unhealthy connections, categorize failure types, and improve error visibility.

We classify connection job failures into three categories based on responsibility for resolution:

* **Leen**: Issues originating from Leen's infrastructure or code. We prioritize these failures and work to resolve them as quickly as possible.
* **Customer**: Failures due to invalid or expired credentials. Customer must update credentials to resolve the failure.
* **Vendor**: Failures caused by the Vendor’s API, such as network issues or 5xx errors. These failures are often temporary and may resolve automatically in subsequent runs.

## How to find Connection Health

You can use [List Connections](/api-reference/provisioning/list-connections) or [Get Connection by ID](/api-reference/provisioning/get-connection). Here is an example response with connection health value:

```json theme={null}
{
    ...
    "health": {
        "name": "HEALTHY",
        "status": "HEALTHY",
        "description": "Connection is healthy",
        "resolution_owner": "LEEN",
        "details": null
    }
}
```

## Connection Health Statuses

| Name                      | Status    | Resolution Owner | Description                        |
| ------------------------- | --------- | ---------------- | ---------------------------------- |
| **HEALTHY**               | HEALTHY   | LEEN             | Connection is healthy              |
| **EXECUTION\_TIMEOUT**    | UNHEALTHY | LEEN             | Execution timeout                  |
| **RATE\_LIMIT\_EXCEEDED** | UNHEALTHY | LEEN             | Rate limit exceeded                |
| **VENDOR\_CLIENT\_ERROR** | UNHEALTHY | LEEN             | Vendor returned a 4xx client error |
| **INTERNAL\_ERROR**       | UNHEALTHY | LEEN             | Internal error                     |
| **VENDOR\_SERVER\_ERROR** | UNHEALTHY | VENDOR           | Vendor returned a 5xx server error |
| **UNAUTHORIZED**          | UNHEALTHY | CUSTOMER         | Connection is unauthorized         |

## Resolving Unauthorized Connections

Unauthorized connections occur when Leen cannot pull data from a vendor due to invalid, insufficient, or revoked permissions or credentials.

Here are two important scenarios for connections that can show up as `UNAUTHORIZED` in your dashboard.

1. **Partial Data Access**: Some connections involve multiple types of data exports. An "unauthorized" status may occur if one or more data types lack the necessary permissions.

2. **Post-Creation Authorization Changes**: Even after a successful initial connection, a connection can become unauthorized. This may happen if the user revokes access to the service account/ API Token or if the credentials expire.

Follow the steps below to identify and resolve Unauthorized connections in your environments.

### Step 1: Identify Unauthorized Connections

Retrieve all connections with an unauthorized status using the following API request:

```sh theme={null}
curl --request GET \
  --url 'https://api.leen.dev/v1/provisioning/organizations/<ORGANIZATION_ID>/connections?healthStatusCodes=UNAUTHORIZED' \
  --header 'X-API-KEY: <API_KEY>'
```

#### Example Response

```json theme={null}
{
    "count": 1,
    "total": 1,
    "items": [
        {
            "id": "417fe209-111e-4119-8523-3f4895155857",
            "vendor": "SENTINELONE",
            "is_active": true,
            "refresh_interval_secs": 14400,
            "timeout_secs": 1800,
            "organization_id": "113734d5-dedf-474b-a9d4-b1f9b4431f75",
            "state": "ACTIVE",
            "created_at": "2024-03-19T12:54:28.728189Z",
            "updated_at": "2024-07-25T22:45:47.478304Z",
            "health": {
                "name": "UNAUTHORIZED",
                "status": "UNHEALTHY",
                "description": "Connection is unauthorized",
                "resolution_owner": "CUSTOMER",
                "details": [
                    {
                        "data_export_type": "devices",
                        "endpoint": "/web/api/v2.1/agents"
                    },
                    {
                        "data_export_type": "alerts",
                        "endpoint": "/web/api/v2.1/threats"
                    }
                ]
            }
        }
    ]
}
```

### Step 2: Update Connection Credentials

To fix an unauthorized connection, update its credentials using the connection ID from the previous response.

```sh theme={null}
curl --request PATCH \
  --url https://api.leen.dev/v1/provisioning/organizations/<ORGANIZATION_ID>/connections/417fe209-111e-4119-8523-3f4895155857 \
  --header 'X-API-KEY: <API_KEY>' \
  --data '{
  "credentials": {
    "base_url": "<BASE_URL>",
    "api_token": "<API_TOKEN>"
  }
}'
```

If the request is successful, it means the credentials are valid, and the connection will become healthy in the subsequent connection job.