Setup

istari-digital-client is the Python interface to the Istari Digital Platform. This page installs the package and builds a configured Client — the entry point for every other example in this section.

To create your first System end to end, work through Python Client 201 — Your first System and come back here when you start writing your own code.

Requirements

• Python 3.10 or newer. Supported versions are listed on the PyPI project description.
• istari-digital-client 13.2.1, the Python client for Istari Digital Platform 2026.09. The examples below install that version. Each release lists its client under SDK Clients in the release notes. If you are not sure your instance is 2026.09, see Match the client to the registry.
• A Key from the web app — see Credentials below.

Installation

Pick whichever fits how you already work. All three install the same package into an isolated environment.

pip, in a virtual environment:

python -m venv .venv && source .venv/bin/activate
pip install "istari-digital-client==13.2.1"

uv, in a virtual environment:

uv venv && source .venv/bin/activate
uv pip install "istari-digital-client==13.2.1"

uv, as a project — when the code is a repository rather than a one-off script:

uv init my-analysis && cd my-analysis
uv add "istari-digital-client==13.2.1"
uv run python analysis.py

uv add records the dependency in pyproject.toml and pins it in uv.lock, so a colleague reproduces your environment with uv sync. uv run executes in that environment without activating it.

On Windows, activate with .venv\Scripts\activate.

Credentials

In the web app, open avatar → Developer Settings. Click Generate Key, then Download credentials — the credentials file is shown once. It is JSON with clientId, keyId, and key (the private key). The dialog names it istari-credentials.json. Copy the API URL from the Endpoints section on the same page. Details: Developer Settings — Keys.

Put both in a .env file beside your script:

ISTARI_DIGITAL_API_URL=<API URL from Endpoints>
ISTARI_CLIENT_IDENTITY_SERVICE_SECRET_FILE=/absolute/path/to/istari-credentials.json
ISTARI_DIGITAL_IDENTITY_SERVICE_ENABLED=true

Note the ISTARI_CLIENT_ prefix on the file path — it is the only name the client reads for the credentials file. With that path and ISTARI_DIGITAL_API_URL set, Key authentication turns on even when ISTARI_DIGITAL_IDENTITY_SERVICE_ENABLED is absent. The sample sets it to true so the choice is explicit. Set it to false to keep a personal access token while a key file is also configured.

Keep .env and the credentials file out of git, prompts, and chat logs.

Initialize the client

Configuration() reads those names from the environment, so the credential stays out of your code:

from dotenv import load_dotenv
from istari_digital_client import Client, Configuration

load_dotenv()                      # copies .env into the environment

client = Client(Configuration())

python-dotenv installs with the client, so there is nothing else to add. Point load_dotenv("istari.env") at another filename when you already keep credentials elsewhere — the tutorials use istari.env.

Passing the values in code

Constructor arguments override the environment. Use them when the values come from a secret manager, or when one process talks to more than one instance:

from istari_digital_client import Client, Configuration

client = Client(Configuration(
    digital_api_url="https://api.your-instance.istari.app",
    identity_service_secret_file="/absolute/path/to/istari-credentials.json",
    identity_service_enabled=True,
))

Identity Service secrets should only be used when the Identity Service is enabled.

Personal Access Tokens

Deprecated

PATs are deprecated as of the July 2026 release and have been superseded by Keys. Support for PATs will be removed from the platform in a future release.

Which change matches your script is on Move a Python script from a PAT to a key. The CLI exchange itself is PAT → Key Exchange.

A PAT uses two names instead of the three above — ISTARI_REGISTRY_URL and ISTARI_REGISTRY_AUTH_TOKEN in .env, or the matching arguments:

client = Client(Configuration(
    registry_url="https://your-instance.istari.digital",
    registry_auth_token="your-personal-access-token",
))

The Registry URL is in the Endpoints section of Developer Settings; see Personal Access Tokens for the token itself.

Next steps

• Patterns — the calls behind common workflows.
• Keys — turn a personal access token into a key file, or list and revoke keys, with client.keys.
• Branching and change requests — commit Resources to a branch and merge a change request.
• Folders in a System — arrange a System's tree from Python.
• V3Client quick start — the unified resource API.

Match the client to the registry

This page installs istari-digital-client 13.2.1 for Istari Digital Platform 2026.09. Use the commands in Installation when your instance is that release.

If you are not sure, run check-registry-readiness.py. It reads the registry version from your instance and prints the istari-digital-client pin that matches it. Create the .env file in Credentials first. The script reads that file.

python -m pip install pyjwt
python -c "import urllib.request; urllib.request.urlretrieve('https://docs.istaridigital.com/quickstart/check-registry-readiness.py', 'check-registry-readiness.py')"
python check-registry-readiness.py

The first two lines of output are registry_version= and sdk_version=. Install the version printed after sdk_version=.

A Key is the credential the script uses: ISTARI_DIGITAL_API_URL and ISTARI_CLIENT_IDENTITY_SERVICE_SECRET_FILE in .env. PyJWT is required for a Key. A personal access token also works when the Key file is unset: set ISTARI_REGISTRY_URL and ISTARI_REGISTRY_AUTH_TOKEN in the same .env. The script prints the versions only. The Key and the token stay in .env.