Configuration

The Configuration class holds the connection settings and runtime tuning passed to Client and V3Client: registry or gateway URL, identity service key, retries, cache, upload, logging, and proxy.

Configuration() reads the environment names below. Constructor arguments override them. One of registry_url or digital_api_url is required. When s3_direct_upload_enabled is true, s3_bucket_name is required.

See Setup for the key file and the three environment variables a script usually sets.

Attributes

Name	Type	Description
digital_api_url	Optional[str]	Service-router gateway URL (ISTARI_DIGITAL_API_URL). When set, registry traffic goes to <digital_api_url>/registry and this wins over registry_url. The client reaches the identity service at <digital_api_url>/identity.
registry_url	Optional[str]	Direct registry URL (ISTARI_REGISTRY_URL). Used when digital_api_url is unset.
registry_auth_token	Optional[str]	Personal access token (ISTARI_REGISTRY_AUTH_TOKEN). Deprecated. See Setup.
identity_service_enabled	Optional[bool]	Authenticate with an auto-refreshed JWT from the identity service instead of a personal access token (ISTARI_DIGITAL_IDENTITY_SERVICE_ENABLED). Default None, which lets the client choose; see Key or personal access token.
identity_service_secret_file	Optional[str or Path]	Path to the JSON key file (ISTARI_CLIENT_IDENTITY_SERVICE_SECRET_FILE). Preferred when both the file and the inline secret are set.
identity_service_secret	Optional[str]	Inline key: base64 JSON {clientId, keyId, key} (ISTARI_CLIENT_IDENTITY_SERVICE_SECRET).
identity_url	Optional[str]	Direct identity service URL (ISTARI_IDENTITY_URL), used when digital_api_url is unset. With digital_api_url set, the client reaches the identity service through the gateway instead.
identity_api_version	IdentityApiVersion or str	Which identity service API the client uses (ISTARI_IDENTITY_API_VERSION): "auto" (the default), "v1" or "v2". See Identity API version.
identity_service_required	bool	When True, the client must use the identity service; see Key or personal access token. Default False (ISTARI_DIGITAL_IDENTITY_SERVICE_REQUIRED).
http_request_timeout_secs	Optional[int]	Per-request timeout (ISTARI_CLIENT_HTTP_REQUEST_TIMEOUT_SECS).
retry_enabled	Optional[bool]	Retry failed requests. Default True (ISTARI_CLIENT_RETRY_ENABLED).
retry_max_attempts	Optional[int]	ISTARI_CLIENT_RETRY_MAX_ATTEMPTS.
retry_min_interval_millis	Optional[int]	ISTARI_CLIENT_RETRY_MIN_INTERVAL_MILLIS.
retry_max_interval_millis	Optional[int]	ISTARI_CLIENT_RETRY_MAX_INTERVAL_MILLIS.
retry_jitter_enabled	Optional[bool]	Default True (ISTARI_CLIENT_RETRY_JITTER_ENABLED).
filesystem_cache_enabled	Optional[bool]	Default True (ISTARI_CLIENT_FILESYSTEM_CACHE_ENABLED).
filesystem_cache_root	Path	ISTARI_CLIENT_FILESYSTEM_CACHE_ROOT.
filesystem_cache_clean_on_exit	Optional[bool]	Default True (ISTARI_CLIENT_FILESYSTEM_CACHE_CLEAN_BEFORE_EXIT).
multipart_chunksize	Optional[int]	Multipart part size in bytes. Default 128 MiB (ISTARI_CLIENT_MULTIPART_CHUNKSIZE).
multipart_threshold	Optional[int]	Size above which an upload is multipart. Default 2 GiB (ISTARI_CLIENT_MULTIPART_THRESHOLD).
s3_direct_upload_enabled	Optional[bool]	Upload bytes directly to S3. Default False (ISTARI_CLIENT_S3_DIRECT_UPLOAD).
s3_bucket_name	Optional[str]	Required when direct upload is enabled (ISTARI_CLIENT_S3_BUCKET_NAME).
log_level	Optional[str]	Default INFO (ISTARI_CLIENT_LOG_LEVEL).
log_to_file	Optional[bool]	Default False (ISTARI_CLIENT_LOG_TO_FILE).
log_file_path	Optional[str]	ISTARI_CLIENT_LOG_FILE_PATH.
proxy_url	Optional[str]	Forward proxy for outbound HTTP(S), for example http://proxy.corp:8080 (ISTARI_CLIENT_PROXY_URL). Overrides HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY. NO_PROXY still applies. SOCKS proxies are not supported.
ca_bundle	Optional[str]	PEM CA bundle for TLS verification (ISTARI_CLIENT_CA_BUNDLE). Overrides REQUESTS_CA_BUNDLE and SSL_CERT_FILE.
trust_env	Optional[bool]	When False, ignore proxy and CA environment variables. Explicit proxy_url and ca_bundle still apply. Default True (ISTARI_CLIENT_TRUST_ENV).
tags	Optional[list[str]]	Endpoint tags whose API hashes the client sends (for example ["Agent", "Model"]). None sends every known hash. No environment variable.
datetime_format	str	"%Y-%m-%dT%H:%M:%S.%f%z". Not a constructor argument.
date_format	str	"%Y-%m-%d". Not a constructor argument.

Two attributes also read an alias environment variable that begins with ISTARI_CLIENT_ instead of ISTARI_DIGITAL_: ISTARI_CLIENT_IDENTITY_SERVICE_ENABLED and ISTARI_CLIENT_IDENTITY_SERVICE_REQUIRED. When both names are set, the ISTARI_DIGITAL_ one wins.

Differences in 13.1.x

This page describes istari-digital-client 13.2.0 and later. In 13.1.x:

• identity_url, identity_api_version, identity_service_required and resolved_identity_api_version() do not exist.
• identity_service_enabled defaults to False, and turning it on requires digital_api_url.

Identity API version

The identity service has two APIs, v1 and v2. identity_api_version chooses which one the client uses. IstariAdmin.identity needs v2.

• "auto", the default, sends no request when the client is constructed. The first token fetch tries the v2 token endpoint, and settles on v1 when the identity service does not serve /api/v2.
• "v1" and "v2" use that API without checking.
• Any other value raises ConfigurationError at construction.

Configuration.resolved_identity_api_version() reports the version in force. Under "auto" it may fetch a token to settle the version, and raises IdentityServiceError if that fails. For a client that authenticates with a personal access token, it returns V2 under "auto" without checking; IstariAdmin.identity still needs a key.

After construction, identity_api_version holds an IdentityApiVersion member, which compares equal to its string. Import the enum with from istari_digital_client import IdentityApiVersion.

Key or personal access token

The client authenticates with a key or a personal access token, by the first rule below that applies. A key here is identity_service_secret_file or identity_service_secret, or their environment variables. A personal access token is registry_auth_token or ISTARI_REGISTRY_AUTH_TOKEN.

1. identity_service_required is True: the key. Without a key, construction raises ConfigurationError.
2. identity_service_enabled is False: the personal access token, even when a key is configured.
3. identity_service_enabled is unset, and the key or a URL (digital_api_url or identity_url) is missing: the personal access token. A key without a URL logs a warning, unless the key comes only from the environment and a personal access token is passed as an argument.
4. A personal access token is passed as an argument, and the key comes only from the environment: the personal access token.
5. A key is configured: the key. This includes a key and a personal access token that both come from the environment.
6. identity_service_enabled is True with no key: the personal access token, or ConfigurationError when there is none.

Construction also raises ConfigurationError when the client would use a key that cannot be read or parsed. It does the same when identity_service_required or identity_service_enabled is True, the client uses the key, and no URL is set.

A Configuration with no key and no personal access token is created without error when neither identity_service_required nor identity_service_enabled is True. Creating a Client from it raises ConfigurationError.

Methods

Name	Description
auth_settings	Bearer auth settings dict used by the API client.
resolved_identity_api_version()	The identity service API version in force: IdentityApiVersion.V1 or V2. See Identity API version.

Key lifecycle calls live on client.keys, not on Configuration.