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 or Get Connection by ID. Here is an example response with connection health value:

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

Connection Health Statuses

NameStatusResolution OwnerDescription
HEALTHYHEALTHYLEENConnection is healthy
EXECUTION_TIMEOUTUNHEALTHYLEENExecution timeout
RATE_LIMIT_EXCEEDEDUNHEALTHYLEENRate limit exceeded
VENDOR_CLIENT_ERRORUNHEALTHYLEENVendor returned a 4xx client error
INTERNAL_ERRORUNHEALTHYLEENInternal error
VENDOR_SERVER_ERRORUNHEALTHYVENDORVendor returned a 5xx server error
UNAUTHORIZEDUNHEALTHYCUSTOMERConnection 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:

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

Example Response

{
    "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.

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.