---
title: Usage Guideline + Authentication
slug: sdk/Usage-Guideline-Authentication
docTags: 
createdAt: 2025-03-20T19:53:50.757Z
---

This section walks through SDK conventions and module-by-module authentication patterns. Each subsection covers a single SDK area with the imports it needs, the connection it expects, and the full set of operations available.

If you only need to get started, see [Getting Started](docId\:MbvG4XlPn9VVydjsdyOVP). If you need a deeper look at connection setup (multiple devices, refresh, disable), see [Managing Connections](docId\:vwtFo9SXcMRbFX9cAfENw). To use any of these from the shell instead of Python, see [Litmus CLI Reference](docId\:s7O-dG4pyackxxPsOJ2Qf).

## In This Section

- [Air gap Features](docId\:dmvQ8b6h_Macksn07230r) - building deployment templates without internet access on the target
- [DeviceHub](docId\:yxCOrVuyOocKWRIWiBFVd) - devices and tags
- [DeviceHub Drivers](docId\:EhmsNvgYqkxU0IWKfGtQ4) - drivers, bundled templates, JSON-schema validation
- [Digital Twins](docId\:rVI0-UxY2VVGeAzEtbnLu) - models, instances, attributes, transformations
- [Flows Manager](docId\:llYidMWF8xC7eVU7mJIk6) - Node-RED flow lifecycle
- [Analytics](docId\:qmFB3pk7t2EmJQehtYNS-) - processors, instances, AI/ML models, variables
- [Integrations](docId:-RvwUF5WrNpI9OKK3dhfb) - cloud connector instances, topics, subscriptions, object storage
- [Marketplace](docId\:IcvppoqLgzSL0OJ7A5DxR) - container images, registries, running containers
- [OPC](docId\:bJ75KdfEjPmrR1fHexJhf) - OPC UA server hierarchy, security, users
- [System](docId:2uxKYv1gxeGJJgnS30zyJ) - users, tokens, network, certificates, events, templates, services
- [Litmus Edge Manager (LEM)](docId\:plT0zva30mtxKY0dB8iLE) - multi-device deployments, applications, alerts, certificates, AI models, MPC

## SDK Conventions

A few patterns recur across every module:

### Default Connection

Most functions accept an optional `le_connection` (LE-side) or `connection` (LEM-side) keyword argument. If omitted, the SDK loads a cached default connection from environment variables on first call. See [Managing Connections](docId\:vwtFo9SXcMRbFX9cAfENw) for the env vars and connection modes.

### Pydantic Models vs Raw JSON

Functions that fetch data return Pydantic models by default (e.g. `Device`, `Tag`, `Driver`). Pass `raw=True` to skip validation and get the API JSON unchanged:

```python
parsed = devices.list_devices()             # list[Device]
raw = devices.list_devices(raw=True)        # list[dict[str, Any]]
```

`raw=True` is useful when:

- The API schema drifts ahead of your installed SDK version (you don't want validation failures).
- You only need a few fields and don't want the model overhead.
- You're piping JSON to another system.

Coverage of `raw=True` varies by function. Check signatures in your IDE or via `litmus-sdk-cli list <module>`.

### Version Gating

Functions that exist only on Litmus Edge 4.0.x raise `UnsupportedVersionError` when called against a 3.x device. The exception names the feature and the minimum required version, so you can branch on it.

### Async (LEM only)

Some long-running LEM task functions accept `async_=True` to return an `asyncio.Task[bool]` instead of blocking.