Skip to main content
Version: 2026.08

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.0.0, the client released with this platform version — see Release notes. The examples below install exactly that version.
  • 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.0.0"

uv, in a virtual environment:

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

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.0.0"
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 key is shown once. 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/key.json
ISTARI_DIGITAL_IDENTITY_SERVICE_ENABLED=true

Note the ISTARI_CLIENT_ prefix on the key path — it is the only name the client reads for the key. ISTARI_DIGITAL_IDENTITY_SERVICE_ENABLED defaults to off, so a key that is set but not enabled is ignored and the first call fails as unauthenticated.

Keep .env and the key 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/key.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.

See the PAT → Key Exchange guide to migrate to keys.

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​