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. Identity Service mode derives its base URL as <digital_api_url>/identity. |
identity_url | Optional[str] | Direct identity-service base URL (ISTARI_IDENTITY_URL). Used when digital_api_url is unset. The gateway derivation wins when both are set. |
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. Left unset, this turns on when a key and an identity URL are both configured (digital_api_url or identity_url). Environment: ISTARI_DIGITAL_IDENTITY_SERVICE_ENABLED, or the alias ISTARI_CLIENT_IDENTITY_SERVICE_ENABLED. An explicit false leaves it off. |
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). A key file or inline secret that cannot be read raises ConfigurationError at construction when an identity URL is configured and no registry_auth_token argument overrides it. |
identity_api_version | IdentityApiVersion | Which identity-service API this client uses. Default AUTO (ISTARI_IDENTITY_API_VERSION). auto tries /api/v2/oauth2/token on the first token fetch and uses v1 when that route is absent. v1 and v2 skip detection. After construction the attribute is a member (AUTO, V1, V2). A member equals its string ("auto", "v1", "v2"). Import with from istari_digital_client import IdentityApiVersion. |
identity_service_required | bool | Default False (ISTARI_DIGITAL_IDENTITY_SERVICE_REQUIRED, alias ISTARI_CLIENT_IDENTITY_SERVICE_REQUIRED). When True, identity-service auth is required even if identity_service_enabled is false, and a missing key raises ConfigurationError. |
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. |
Methods
| Name | Description |
|---|---|
auth_settings | Bearer auth settings dict used by the API client. |
resolved_identity_api_version() | The identity API version in force: IdentityApiVersion.V1 or V2. Settling auto fetches a token and can raise IdentityServiceError. |
Key lifecycle calls live on client.keys, not on Configuration.