Keys

client.keys creates, lists, and revokes the Key a Python script uses to sign in. The same object exists on Client and on V3Client. You always call it as client.keys.some_method(), for example client.keys.list().

Most scripts never need this page. Download a key once from the web app (avatar → Developer Settings → Generate Key) and follow Setup. Which change matches a script that still uses a personal access token is on Move a Python script from a PAT to a key. Come here when you want to do that from code: turn a personal access token into a key file, add another key, or revoke one.

The same job on the command line is stari key exchange. Creating an agent that signs in with its own key is a different call, create_agent_with_key().

Which call to use

You want to	Call
Turn the personal access token in your Configuration into a new key file	generate_keypair_and_exchange()
Do that exchange with a keypair you already created	exchange_pat()
Add a new key while you are already signed in with a key	generate_keypair_and_register()
Register a keypair you already created	register()
See the keys on your account	list()
Look up one key, or revoke it	get(), revoke()

list and get return names and ids only. The private key is never sent back. Save it from the result of an exchange or a register call, or you cannot sign in with that key later.

What you need first

Exchanging a personal access token (generate_keypair_and_exchange, exchange_pat) needs the API URL from Developer Settings → Endpoints as digital_api_url. The token is registry_auth_token on the same Configuration, or the pat= argument. Identity Service mode can stay off for this step. Personal access tokens are deprecated; the point of the exchange is to stop using one.

Listing, registering, and revoking need a client that is already signed in with a key: identity_service_enabled=True and identity_service_secret_file (or identity_service_secret), as in Setup.

Replace a personal access token

from istari_digital_client import Client, Configuration

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

result = client.keys.generate_keypair_and_exchange(name="laptop")
result.write_credentials_json("/absolute/path/to/key.json")

write_credentials_json writes the private key as JSON and restricts the file to the current user. Keep that file out of git. The next script signs in with it:

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,
))

result.to_identity_service_secret() returns the same credential as one base64 string, for identity_service_secret= when you store it in a secret manager instead of a file.

Arguments that show up everywhere

• kind — PrincipalKind.USER (the default, a person) or PrincipalKind.AGENT. Import it with from istari_digital_client import PrincipalKind.
• principal_id — whose keys you mean. "me" is the signed-in user, and it is the default. For an agent, pass that agent's id. An agent cannot list, register, or revoke its own keys; an administrator does that and passes the agent's id.
• name — a label such as "laptop". Leave it out and the platform uses the key id as the label.
• pat — the personal access token to exchange. Leave it out to use registry_auth_token from Configuration.
• retry_policy — leave it out. The client uses the retry settings on Configuration.
• api_version — IdentityApiVersion or "auto", "v1", or "v2". Default "auto". Import it with from istari_digital_client import IdentityApiVersion. Under "auto", list, get, revoke, and register use the v2 key routes when this client is on identity-service v2 and the call can be expressed there. Register with username or display_name, and the personal access token exchange, stay on the v1 routes. "v2" raises ConfigurationError for those calls before any request.

Exchange a personal access token

generate_keypair_and_exchange()

Creates a new P-384 keypair and exchanges your personal access token for it, in one call. This is the call in the example above.

• Parameters:

  • pat (str, optional) — Token to exchange. Defaults to registry_auth_token.
  • kind (PrincipalKind) — USER by default. AGENT exchanges an agent's token; an administrator runs that.
  • key_id (str, optional) — Id to assign. A random id is chosen when you leave this out.
  • name (str, optional) — Label. Blank becomes the key id.
  • retry_policy (RetryPolicy, optional)
  • api_version (IdentityApiVersion or str, optional) — "auto" by default. See Arguments that show up everywhere.

• Return Type: ExchangePatResult. Call write_credentials_json(path) or to_identity_service_secret() before you discard it. Also includes client_id, key_id, tenant_id, user_uuid, and name.

exchange_pat()

Same exchange, using a P-384 keypair you already hold in a GeneratedClientCredentials object. Reach for generate_keypair_and_exchange() when you do not have one yet.

• Parameters:

  • credentials (GeneratedClientCredentials) — The keypair. The public key is registered; the private key stays on the result. (required)
  • pat (str, optional)
  • kind (PrincipalKind) — Default USER.
  • validate_public_key (bool) — Default True. Checks that the public key is P-384 before sending it.
  • name (str, optional)
  • retry_policy (RetryPolicy, optional)
  • api_version (IdentityApiVersion or str, optional) — "auto" by default. See Arguments that show up everywhere.

• Return Type: ExchangePatResult

Add, list, and revoke keys

These calls run only after the client is signed in with a key.

generate_keypair_and_register()

Creates a P-384 keypair and registers it for someone who already has an account. With no arguments, that someone is you.

• Parameters:

  • principal_id (str, optional) — Defaults to your own id. Pass an agent's id, together with kind=PrincipalKind.AGENT, when an administrator is creating a key for that agent.
  • kind (PrincipalKind) — Default USER.
  • key_id (str, optional) — Random when omitted.
  • name (str, optional)
  • retry_policy (RetryPolicy, optional)
  • api_version (IdentityApiVersion or str, optional) — "auto" by default. See Arguments that show up everywhere.

• Return Type: RegisterKeyResult. metadata describes the key (key_id, name, algorithm, created_at, expires_at). write_credentials_json(path) saves the private key.

register()

Registers a P-384 public key from a GeneratedClientCredentials object you already have.

• Parameters:

  • credentials (GeneratedClientCredentials) — (required). Only the public key and key id are sent.
  • principal_id (str) — Default "me".
  • kind (PrincipalKind) — Default USER.
  • validate_public_key (bool) — Default True.
  • name (str, optional)
  • username (str, optional) — Used when an administrator registers the first key for an agent that does not exist yet.
  • display_name (str, optional) — Display name for that new agent.
  • retry_policy (RetryPolicy, optional)
  • api_version (IdentityApiVersion or str, optional) — "auto" by default. See Arguments that show up everywhere.

• Return Type: KeyMetadata

list()

Lists keys for the signed-in user, or for the agent id you pass. Each entry is metadata: key_id, name, algorithm, created_at, and expires_at when the key expires.

• Parameters:

  • principal_id (str) — Default "me".
  • kind (PrincipalKind) — Default USER.
  • retry_policy (RetryPolicy, optional)
  • api_version (IdentityApiVersion or str, optional) — "auto" by default. See Arguments that show up everywhere.

• Return Type: PrincipalKeys. The keys are on .keys.

get()

Returns the same metadata for one key.

• Parameters:

  • key_id (str) — (required)
  • principal_id (str) — Default "me".
  • kind (PrincipalKind) — Default USER.
  • retry_policy (RetryPolicy, optional)
  • api_version (IdentityApiVersion or str, optional) — "auto" by default. See Arguments that show up everywhere.

• Return Type: KeyMetadata

revoke()

Deletes one key. A script still holding that key file can no longer sign in with it.

• Parameters:

  • key_id (str) — (required)
  • principal_id (str) — Default "me".
  • kind (PrincipalKind) — Default USER.
  • retry_policy (RetryPolicy, optional)
  • api_version (IdentityApiVersion or str, optional) — "auto" by default. See Arguments that show up everywhere.

• Return Type: None

client_id

A property, read as client.keys.client_id (no parentheses). It is the Identity Service client id of the key this process is signed in with, and it requires Identity Service mode. list() and get() already default to this caller, so you only need the value when another API asks for your id.