Move a Python script from a PAT to a key

Deprecated

Personal access tokens (PATs) are deprecated as of the July 2026 release. Keys replace them for programmatic access to the Istari Digital Platform. An existing PAT still signs in until it is revoked. On an instance where keys are available, a new PAT cannot be created. Support for PATs will be removed in a future release.

A Python script signs in through Configuration on Client or V3Client. The change depends on how that object is built today, and on whether this instance has keys turned on. Every path on this page ends the same way: Client(Configuration()) after the environment is loaded, with a key in that environment. Install and the credential screen are on Setup.

See whether this instance uses keys

Check this before you change a script. Any signed-in user can open the page.

In the web app, click your avatar, then Developer. The address on your instance is /settings?tab=developer-settings.

What you see	Keys on this instance
An Access Keys section is on the page. Under Personal Access Tokens, a banner reads Personal Access Token creation is disabled.	On. New credentials are keys. Continue with the case that matches your script.
Generate New Token is the button on Personal Access Tokens. The page has no Access Keys section.	Off. This instance still issues PATs. Keep the token you have.

On the first row, the line under the Personal Access Tokens title is "Creation is disabled — use Access Keys for new credentials."

Keys need the Identity Service. When the table says keys are off, ask an administrator to enable it before you create or exchange a key. Details of the cards: Developer Settings — Keys.

Where the script should end up

from dotenv import load_dotenv
from istari_digital_client import Client, Configuration

load_dotenv()  # copies .env into the environment

client = Client(Configuration())

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

Configuration() reads those names from the environment, so the credentials stay out of the source. The ISTARI_CLIENT_ prefix on the file path is required. 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. Keep .env and the credentials file out of git.

Download credentials writes that file. The dialog names it istari-credentials.json; the saved name is istari-credentials-<keyId>.json. Access Keys is the section that lists it. The file itself holds three fields, and key is the private key, shown only in this download:

{
  "clientId": "<client id>",
  "keyId": "<key id>",
  "key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
}

The API URL is in avatar → Developer → Endpoints. Full steps: Setup — Credentials and Initialize the client.

Choose the heading that describes your current setup.

If the PAT is written in your script

You are here when the constructor receives the PAT as registry_auth_token:

from istari_digital_client import Client, Configuration

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

That call still signs in when the token was created for this instance, it has not been revoked, and the server still accepts PATs. A notebook cell that pastes the same string is the same case. Developer Settings will not issue a replacement PAT once keys are on.

Move the token out of the source:

1. Put the registry URL and the token in a .env file beside the script:

   ISTARI_REGISTRY_URL=https://your-instance.istari.digital
   ISTARI_REGISTRY_AUTH_TOKEN=your-personal-access-token

   The Registry URL is in Endpoints on the same Developer page. See Personal access tokens.

2. Change the script to the load_dotenv() form in Where the script should end up. Drop registry_url and registry_auth_token from the constructor.

3. Confirm a call still succeeds. The script is still using the PAT; the token is just out of the source.

4. When keys are on, follow Switch the environment to a key. When keys are off, stop here and ask an administrator to enable the Identity Service.

If your script expects a credentials file

You are here when the constructor names a key file:

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_secret_file is the path to that credentials file.

The key file is already on disk

Pass that path and the API URL, with identity_service_enabled=True. The script signs in. Moving those three values into .env, as in Where the script should end up, keeps the path out of the source.

You only have a PAT

Create a key, then point identity_service_secret_file at the file. This step needs keys on. When keys are off, keep signing in with registry_auth_token until an administrator enables the Identity Service.

Create the key in one of these ways:

Generate a key in the web app

1. Open avatar → Developer (/settings?tab=developer-settings).
2. In Access Keys, click Generate Key, then Download credentials. The credentials file is shown once.
3. Copy the API URL from Endpoints on the same page.
4. Pass that URL as digital_api_url and the downloaded file as identity_service_secret_file, with identity_service_enabled=True.

The dialog, expiration, and revoke control: Developer Settings — Keys.

Exchange the PAT with the CLI

Use the CLI when the token should become a key file, including a token that was only ever in the Python script.

Install the CLI if it is not on the machine. The exchange runs only when keys are on. The CLI also needs the API URL first. Both prerequisites, and the other flags, are on PAT → Key Exchange.

For the token from the script:

stari key exchange --pat "REPLACE_WITH_PAT" --output /path/to/create/key/file.json

That writes the key file and leaves the CLI config as it is. Point identity_service_secret_file at the file. Other flags — an existing key file, an agent token, rewriting the CLI's own config — are on that page. If the CLI is already signed in with this same PAT, stari key exchange with no arguments also switches the CLI; the guide covers that command.

The exchange leaves the PAT in place. Confirm the script signs in with the key, then revoke the token if nothing else uses it.

Exchange the PAT from Python

The client can run the same exchange when you do not want to install the CLI. Sign in once with digital_api_url and registry_auth_token, call client.keys.generate_keypair_and_exchange(), and write the file it returns. The call, and the single-string form for a secret manager, are on Keys — Replace a personal access token.

If your script already loads credentials from the environment

You are here when the source does not name a token or a key file:

from dotenv import load_dotenv
from istari_digital_client import Client, Configuration

load_dotenv()
client = Client(Configuration())

Keep this. Constructor arguments override the environment when one process talks to more than one instance; Setup shows that form.

The environment holds a PAT

These two names still work:

ISTARI_REGISTRY_URL=https://your-instance.istari.digital
ISTARI_REGISTRY_AUTH_TOKEN=your-personal-access-token

load_dotenv() with no argument reads .env beside the script. Pass a path, load_dotenv("path/to/file"), when the names live in another file. The token itself is under Personal access tokens.

Switch the environment to a key

Create the key in the web app, or exchange the PAT with the CLI, using the options above. Then replace the two PAT lines with the three key lines in Where the script should end up.

Remove ISTARI_REGISTRY_URL and ISTARI_REGISTRY_AUTH_TOKEN after a call succeeds with the key. With the key path and ISTARI_DIGITAL_API_URL set, and ISTARI_DIGITAL_IDENTITY_SERVICE_ENABLED left unset, the key is what signs in, including when those PAT lines are still in the environment. Set ISTARI_DIGITAL_IDENTITY_SERVICE_ENABLED=false to keep the token while the key file is also configured.

If a pipeline or secret manager provides the credentials

The script stays on Client(Configuration()). The pipeline or the secret manager sets the variables before the process starts.

• To keep the PAT for now, store ISTARI_REGISTRY_URL and ISTARI_REGISTRY_AUTH_TOKEN.
• To move to a key, store the key and set the three key variables. A store that takes one string uses ISTARI_CLIENT_IDENTITY_SERVICE_SECRET (the base64 form from to_identity_service_secret()). See Keys.

Each person uses their own key.

If the CLI or an agent still uses a PAT

When stari or an agent is what still signs in with a PAT, follow PAT → Key Exchange. stari key exchange rewrites the CLI config. stari key exchange --agent does the same for an agent that already has a PAT.

After the script signs in with a key

Revoke the PAT under avatar → Developer once no script, CLI, or agent still uses it. See Revoke tokens.

Client.check_auth_deprecation() reports whether this process is still signing in with a PAT on a server that accepts keys. See PAT deprecation.