Agent keys
An agent authenticates to the platform with an Identity Service key, available when the Identity Service is enabled. A Tenant Administrator or Platform Administrator (on installations without tenant management, an organization administrator) creates and replaces keys.
Setting up a new host? The key is step 3 of the install guide for that operating system — Windows, Linux, or macOS — where Generate Key in the web app creates the agent along with its key. This page explains the identifiers those steps produce, and covers what comes later: rotating a key and moving an agent off a deprecated PAT.
Which identifier is which
An agent carries several identifiers, and different commands and screens ask for different ones. This table tells them apart.
| Identifier | Example | Who creates it | Where you find it |
|---|---|---|---|
| Client ID, also called the principal ID | 349298050906207909 | The platform, when Generate Key creates the agent | The clientId field of the credentials file. Client ID on the agent's Keys tab in the web app. |
| Key ID | a UUID | The platform, when it creates the key | The keyId field of the credentials file, the Key ID column on the Keys tab, and the name of the file the web app downloads, agent-credentials-<key id>.json. |
| Key name | lab-01-aug-2026 | You, in the Agent name (optional) box of Generate Key, or the platform when you leave it blank. Despite the box's label, this value names the key and the agent's Identity Service identity, not the Agent name below. | The Name column on the Keys tab. It is a label to help you recognize a key. Nothing authenticates with it. |
| Private key | a -----BEGIN PRIVATE KEY----- block | The platform, when it creates the key | The key field of the credentials file, and nowhere else. It is shown once, at creation. |
| Agent ID | a UUID | The platform, the first time the agent starts and registers itself | Under the agent's name in the All Agents table, with a control to copy it. On the host, in the istari_agent_id file. |
| Agent name | Lab workstation 01 | The platform assigns one. Set istari_digital_agent_display_name to choose your own. | The Agent Name column in All Agents. An agent with no name shows its Agent ID there instead. |
| User UUID and Tenant ID | UUIDs | The Identity Service | The Generate Key dialog. You never pass these to a command. |
An agent has two identities
The platform knows each agent in two places, and each place has its own identifier.
The Identity Service knows the agent as a principal, named by its Client ID. This is the identity the agent proves: it signs a token with its private key, and the platform checks that signature against the public key held for that Client ID. Keys belong to this identity, which is why an agent keeps working when you replace one of its keys.
The registry knows the agent as a record that carries its jobs, modules, status, and name, named by its Agent ID. The agent creates that record itself the first time it starts, and saves the UUID in istari_agent_id so it comes back as the same agent after a restart. Delete that file and the agent registers again as a new agent, leaving the old record behind.
The platform links the two, which is why the agent's Keys tab can show its Client ID even though the All Agents table shows only the Agent ID.
The agent name and the Client ID are unrelated
The name in the All Agents table is a label for people reading the screen. The Client ID is what the agent authenticates as. Changing one has no effect on the other, and neither can be derived from the other.
The consequence worth knowing: the name is not a way to find the Client ID. Read the credentials file or the Keys tab instead.
Find an agent's Client ID
Its credentials file is the local answer. istari_digital_config.yaml gives the path in istari_digital_agent_identity_service_secret_file; the clientId in that file is the agent's Client ID. The file is readable only by the account that owns it, so read it as that account:
grep clientId ~/.istari_digital/agent-credentials-<key id>.json
In the web app, open the agent from All Agents and go to its Keys tab, where Client ID sits above the list of keys with a control to copy it.
Create an agent and its key
Generate Key on the Agents page creates the agent's identity along with the key, so there is nothing to create or name beforehand. The install guides use this as step 3; here is the same flow with the configuration keys spelled out.
- On the Agents page, select Generate Key. Give the key a name and select Generate.
- Select Download credentials while the key is on screen. The file,
agent-credentials-<key id>.json, holds the private key and is shown only once. Losing it means generating a new key. - Copy the file onto the agent host, somewhere the account running the agent can read and others cannot.
- Point the agent at it in
istari_digital_config.yaml:
default: {}
agent:
istari_digital_agent_digital_api_url: "https://api.example.istari.app"
istari_digital_agent_identity_service_secret_file: "/path/to/agent-credentials-<key id>.json"
istari_digital_agent_identity_service_enabled: true
The credentials file contains clientId, keyId, and the private key. The agent identifies itself with the clientId, so keep the file intact rather than copying values out of it.
See Generate an agent key for the dialog, and the configuration reference for istari_digital_agent_digital_api_url, istari_digital_agent_identity_service_secret_file, and istari_digital_agent_identity_service_enabled.
Creating the agent from its own host instead. With administrator credentials and the CLI on the host, stari key generate --agent release followed by stari key create-agent --key-file <path> --configure does the same thing without a file to hand over: the keypair is made on the host, the platform creates the agent from it, and --configure writes the three values above. See Creating a new agent with a key.
Replace the key on an existing agent
Do this when a key is compromised, lost, or being rotated, or when moving an agent off a PAT. Unlike creating an agent, these commands act on an existing identity, so they need to know which one — and they run on the CLI, since Generate Key in the web app always creates a new agent rather than adding a key to one that exists.
Moving off a PAT. stari key exchange --agent on the agent host generates a key, registers it, and rewrites the configuration — it reads the agent's identity from the PAT already in the file, so you supply nothing. See PAT → Key Exchange. An agent can also do this for itself when istari_digital_agent_identity_service_auto_migrate is set; it waits until the agent is idle.
Rotating a key. As an administrator, on the agent host, generate a keypair beside the current credentials and register it against the agent's identity:
stari key generate -o ~/.istari_digital/agent-credentials-new.json
stari key register --key-file ~/.istari_digital/agent-credentials-new.json --agent --principal-id <client id> --configure
Run both as the account that owns the agent's configuration and credentials, so the new file lands where the agent can read it and --configure edits the configuration the agent actually loads. The CLI on this host needs your User key to authenticate the registration.
generate writes the keypair and never contacts the network — so you can create it on the host and register it from a machine that holds admin credentials. register sends only the public key and key ID, then rewrites the credentials file so its client ID and key ID match what the server recorded. --configure points the agent section at the new file.
--principal-id takes the agent's Client ID, not the Agent ID under its name in the All Agents table — see Which identifier is which for the difference and Find an agent's Client ID for where to read it. Registering a key against a Client ID that does not exist creates a new identity, which the registry will not accept as an agent, so check the ID before you run the command — Troubleshooting covers the failure that follows.
Afterwards, restart the agent and revoke the old key from Agents → the agent's row → Keys. Revoking takes effect immediately, so confirm the agent is running on the new key first.
PAT authentication
PATs are deprecated as of the July 2026 release and will be removed in a future release. Use a key on any deployment where the Identity Service is enabled.
An agent on a deployment without the Identity Service authenticates with a token instead of a key. Two values go into istari_digital_config.yaml:
- The Agent Registry API URL, from Settings → Developer Settings → Registry Information in the web app. Usually
https://registry.<your-host>. - An agent Personal Access Token, created by an administrator — see Generate an agent token. This is not the same as your own user PAT.
Write them as the account that runs the agent, leaving the Identity Service keys out:
default: {}
agent:
istari_digital_agent_registry_api_url: "https://registry.example.istari.app"
istari_digital_agent_registry_api_token: "<agent PAT>"
The token sits in the file in clear text, so restrict the file to that account. To move this agent onto a key later, see PAT → Key Exchange.