---
name: istari-connect
description: >
  Connect to the Istari Digital Platform from Python with istari-digital-client 13.x —
  resolve credentials, build the Istari / IstariIntegrations / IstariAdmin facade
  clients, check the SDK generation, read errors and pages correctly. Use first in any
  Istari Digital task on SDK 13: "connect to Istari Digital", "auth", or before any
  istari_digital_client code. If the System will have folders, also build Client.
metadata:
  sdk: istari-digital-client
  sdk-major: "13"
  sdk-range: ">=13.0,<14"
  skill-version: "13.0.1"
  verified-sdk: "13.0.1"
  verified-registry: "demo 11.1.0"
  verified-on: "2026-09-06"
---

# istari-connect

> **SDK 13.x — the `Istari` facade.** Verified against istari-digital-client 13.0.1. Check first:
> `python -c "import importlib.metadata as m; print(m.version('istari-digital-client'))"`.

The facade is **beta** in the package (the surface may change). Production code that must match the published Python Client reference should use `Client` / `V3Client` from [SDK setup](/markdown-source/current/developers/SDK/01-setup.md). **If the System will have folders, construct `Client` from the same `Configuration` now** — `branch.commit()` on the facade cannot set folders (`istari-folders`).

## The pattern

```python
from istari_digital_client import Configuration
from istari_digital_client.sdk import Istari, IstariIntegrations, IstariAdmin

# Keys — current credential. Generate under avatar → Developer → Generate Key.
cfg = Configuration(
    digital_api_url=API_URL,
    identity_service_secret_file="/path/to/key.json",
    identity_service_enabled=True,
    http_request_timeout_secs=120,
)
# Personal Access Tokens (deprecated) still work until revoked:
# cfg = Configuration(registry_url=REGISTRY_URL, registry_auth_token=PAT, http_request_timeout_secs=120)

client = Istari(cfg)              # resources, systems, jobs
integrations = IstariIntegrations(cfg)  # functions, modules, tools, agents
admin = IstariAdmin(cfg)          # users, tokens, keys
```

One `Configuration` also constructs `Client` for folders. Never invent a token. If credentials are missing, stop and send the person to Developer Settings — do not ask them to paste a secret in chat.

**UI host** = registry or API host minus the `fileservice[-v2].` or `api.` prefix (`istari-links`).

## Guard the generation

```python
import importlib.metadata as md
v = md.version("istari-digital-client")
assert v.split(".")[0] == "13", f"these notes are for SDK 13.x; installed {v}"
```

## Read answers correctly

- **Pages.** Every `.list()` returns `Page[T]`: `.items`, `.total`, `.has_next()`, `.next_page()`. Iterating the Page walks every page — bound it or read `.items`. `page[0]` raises `TypeError`. `size=` exists on most lists but **not** on `systems.branches.list()`.
- **Errors** subclass `IstariError` (`from istari_digital_client.sdk import IstariError`). Catch `IstariError` and read `str(e)`.
- A missing Resource id often reports as permission denied, not not-found. Check the id family (`istari-models`) before treating it as an access problem.
- The SDK may log a traceback for every non-2xx and a registry-compatibility warning on connect. Silence noise in scripts with `logging.getLogger("istari_digital_client").setLevel(logging.CRITICAL)` (the quickstart uses `logging.disable`). Act on errors, not warnings.

## If this happens

| Signal                                                                 | Meaning                                                                |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `AttributeError: 'Istari' object has no attribute 'get_system'`        | 10.x names — the facade is `client.systems.get(...)`                   |
| `TypeError: Branches.list() got an unexpected keyword argument 'size'` | that list has no paging args                                           |
| Fast identical 500 on a write                                          | validation (for example a 255-character cap), not infra — do not retry |

Docs: [Python Client 201](/markdown-source/current/tutorials/python-client/201-first-system.md), [SDK setup](/markdown-source/current/developers/SDK/01-setup.md).