--- title: Managing Connections slug: sdk/managing-connections docTags: createdAt: 2025-10-06T18:35:26.969Z --- All SDK API calls require a connection to a Litmus Edge instance or a Litmus Edge Manager (LEM) instance. By default the SDK builds this connection automatically from environment variables. You can also create explicit connection objects for multi-device workflows. There are three connection modes: 1. **Direct LE** - OAuth 2.0 to a single Litmus Edge device 2. **Direct LEM** - API token to a Litmus Edge Manager instance (for `litmussdk.lem.*` calls) 3. **LEM Bridge** - route LE calls to a managed Edge device through the Edge Manager *** ## Direct LE Connection ### Generating an OAuth 2.0 Token 1. In your Litmus Edge UI navigate to **System -> Access Control -> Tokens** 2. Press **+** next to *API Credentials* and select **OAuth 2.0 Client** 3. Grant the token **Admin** permissions (lesser permissions are supported but may limit SDK functionality) 4. Copy the **Client ID** and **Client Secret** For more detail see the [How to Create and Use OAuth 2.0 Tokens in Litmus Edge](docId\:vW9e3nuXf2ZATVznJ2_Vm). ### Configuration Set the following environment variables, either in your shell or in a `.env` file in your working directory: ```bash export EDGE_URL=https:// export EDGE_API_CLIENT_ID= export EDGE_API_CLIENT_SECRET= ``` If your device uses a self-signed TLS certificate (common in edge deployments), also set: ```bash export VALIDATE_CERTIFICATE=false ``` `.env`** file example:** ```javascript EDGE_URL=https://192.168.1.100 EDGE_API_CLIENT_ID=my-client-id EDGE_API_CLIENT_SECRET=my-client-secret VALIDATE_CERTIFICATE=false ``` *** ## Direct LEM Connection For `litmussdk.lem.*` calls (companies, lifecycle, digital twin, etc.) that target the LEM API directly. No LE device involved. ### Generating a LEM API Token 1. In the Litmus Edge Manager Admin Console navigate to **Settings -> Tokens -> New** 2. Select the appropriate scope for your use case 3. Under *Token Scope* select the projects the token will access 4. Create the token and copy it ### Configuration ```bash export EDGE_MANAGER_URL=https:// export EDGE_API_TOKEN= ``` :::BlockQuote `EDGE_API_TOKEN` is the **LEM API token** despite the `EDGE_` prefix. This same field is used for both direct LEM calls (above) and the LEM Bridge flow (below). One credential, two flows. ::: *** ## LEM Bridge Connection The LEM bridge lets the SDK communicate with individual Edge devices via the Edge Manager. Useful when the LE devices aren't directly reachable but the LEM is. ### Generating a LEM API Token 1. In the Litmus Edge Manager Admin Console navigate to **Settings -> Tokens -> New** 2. Enable the **Edge API Bridge** scope 3. Under *Token Scope* select the projects the token will access 4. Create the token and copy it ### Configuration ```bash export USE_LEM_BRIDGE=true export EDGE_MANAGER_URL=https:// export EDGE_MANAGER_PROJECT_ID= export EDGE_MANAGER_DEVICE_ID= export EDGE_API_TOKEN= ``` LE traffic is tunneled through LEM's `/api/v1/edge/{project}/{device}` endpoint. Authentication uses the LEM API token (the `EDGE_API_TOKEN` env var) sent as the `X-AuthToken` header. *** ## Environment Variables Reference | Variable | Used by | Description | | ------------------------- | ---------------------- | ------------------------------------------------------- | | `EDGE_URL` | Direct LE | Litmus Edge device URL | | `EDGE_API_CLIENT_ID` | Direct LE | OAuth 2.0 Client ID | | `EDGE_API_CLIENT_SECRET` | Direct LE | OAuth 2.0 Client Secret | | `EDGE_MANAGER_URL` | Direct LEM, LEM Bridge | Litmus Edge Manager URL | | `EDGE_API_TOKEN` | Direct LEM, LEM Bridge | LEM API token, sent as `X-AuthToken` | | `EDGE_MANAGER_PROJECT_ID` | LEM Bridge | Target LEM project ID | | `EDGE_MANAGER_DEVICE_ID` | LEM Bridge | Target Edge device ID within the project | | `EDGE_MANAGER_ADMIN_URL` | (optional) | LEM admin URL, currently unused | | `USE_LEM_BRIDGE` | LEM Bridge | Set to `true` to enable bridge mode | | `VALIDATE_CERTIFICATE` | All | `false` to disable TLS verification (self-signed certs) | | `TIMEOUT_SECONDS` | All | Request timeout in seconds. Default `30` | *** ## Using the Default Connection Once configured, all functions use the default connection automatically: ```python from litmussdk.devicehub import devices all_devices = devices.list_devices() ``` *** ## Managing Multiple Connections To work with more than one device simultaneously, create explicit connection objects via the factories in `litmussdk.utils.conn`: ```python from litmussdk.utils.conn import new_le_connection from litmussdk.devicehub import devices # Default connection (from environment variables) devices.list_devices() # Explicit connection to a different device conn_b = new_le_connection( edge_url="https://192.168.1.100", edge_client_id="my-client-id", edge_client_secret="my-client-secret", ) devices.list_devices(conn_b) ``` Available connection factories: - `new_le_connection(edge_url, client_id, client_secret, validate_certificate=True, timeout_seconds=30)`: direct OAuth 2.0 connection to a Litmus Edge device. - `new_lem_connection(edge_manager_url, edge_manager_admin_url, edge_api_token, validate_certificate=True, timeout_seconds=30)`: direct connection to a Litmus Edge Manager instance. - `new_lem_bridge_connection(edge_manager_url, edge_api_token, project_id, device_id, validate_certificate=True, timeout_seconds=30)`: connection to a LE device via the LEM bridge. *** ## Disabling and Refreshing the Default Connection The SDK caches the default connection per type (LE / LEM) for performance. To clear the cache (for example, after rotating credentials in the env), use the corresponding refresh function: ```python from litmussdk.utils import conn conn.refresh_default_le_connection() # clears the LE connection cache conn.refresh_default_lem_connection() # clears the LEM connection cache ``` To disable automatic loading of the default connection entirely: ```python from litmussdk import config from litmussdk.utils import conn config.disable_default_connection() conn.refresh_default_le_connection() conn.refresh_default_lem_connection() ``` After disabling, calls without an explicit connection will raise. Re-enable with: ```python config.enable_default_connection() ``` *** ## License Copyright (c) Litmus Automation Inc.