Skip to main content
Version: 2026.09

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 client this doc set is written against. The examples below install exactly that version; each release lists its client under SDK Clients in the release notes.
  • A Key from the web app — see Credentials below.

Match the client to the registry​

check-registry-readiness.py reads the registry version from your instance and prints the istari-digital-client pin that matches it. Registry 11.5.0 and newer print 13.2.1, the client this page installs. Older registries print an earlier pin. The full table is in the script.

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 --env istari.env

The first two lines are registry_version= and sdk_version=. Install that pin. The commands in Installation install 13.2.1 for a registry at 11.5.0 or newer. A Key is preferred (ISTARI_DIGITAL_API_URL and ISTARI_CLIENT_IDENTITY_SERVICE_SECRET_FILE; PyJWT is required for that path). A personal access token also works: set ISTARI_REGISTRY_URL and ISTARI_REGISTRY_AUTH_TOKEN, and leave the Key file unset. The script does not print the Key or the token.

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​