wherobots-python-sdk 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

wherobots/__init__.py

@@ -3,6 +3,7 @@
 from wherobots.__version__ import __version__
 from wherobots.api.drive import Files, FilesDrive
 from wherobots.api.files import FilesAPI
+from wherobots.api.tasks import TaskRuns, Tasks
 from wherobots.client import WherobotsJob
 from wherobots.config import WherobotsConfig
 from wherobots.enums import (
@@ -14,6 +15,7 @@ from wherobots.enums import (
     JobStatus,
     Region,
     Runtime,
+    TaskRunState,
     is_terminal_status,
 )
 from wherobots.exceptions import (
@@ -34,6 +36,7 @@ from wherobots.models import (
     KubeAppEvent,
     LogItem,
     LogsResponse,
+    OffsetPage,
     OrganizationCustomer,
     PyPiDependency,
     RunAppMeta,
@@ -46,6 +49,14 @@ from wherobots.models import (
     RunPythonPayload,
     RunView,
     StorageIntegration,
+    Task,
+    TaskExample,
+    TaskRun,
+    TaskRunCost,
+    TaskRunLogEntry,
+    TaskRunLogs,
+    TaskRunSummary,
+    TaskSummary,
     TemporaryAwsCredentials,
     UtilizationStats,
 )
@@ -63,6 +74,8 @@ __all__ = [
     "WherobotsJob",
     "Job",
     "FilesAPI",
+    "Tasks",
+    "TaskRuns",
     "WherobotsConfig",
     # Enums
     "Runtime",
@@ -73,6 +86,7 @@ __all__ = [
     "AppType",
     "DependencyType",
     "DependencyFileType",
+    "TaskRunState",
     "is_terminal_status",
     # Exceptions
     "WherobotsJobError",
@@ -105,4 +119,13 @@ __all__ = [
     "TemporaryAwsCredentials",
     "UtilizationStats",
     "FileEntry",
+    "OffsetPage",
+    "TaskSummary",
+    "Task",
+    "TaskExample",
+    "TaskRunSummary",
+    "TaskRun",
+    "TaskRunLogs",
+    "TaskRunLogEntry",
+    "TaskRunCost",
 ]

wherobots/__version__.py

@@ -1,5 +1,5 @@
 """Version information."""
 
-__version__ = "0.5.1"
+__version__ = "0.7.0"
 __author__ = "Wherobots"
 __email__ = "support@wherobots.com"

wherobots/api/__init__.py

@@ -4,5 +4,6 @@ from wherobots.api.base import BaseClient
 from wherobots.api.drive import Files, FilesDrive
 from wherobots.api.files import FilesAPI
 from wherobots.api.runs import RunsAPI
+from wherobots.api.tasks import TaskRuns, Tasks
 
-__all__ = ["BaseClient", "Files", "FilesAPI", "FilesDrive", "RunsAPI"]
+__all__ = ["BaseClient", "Files", "FilesAPI", "FilesDrive", "RunsAPI", "TaskRuns", "Tasks"]

wherobots/api/base.py

@@ -1,7 +1,8 @@
 """Low-level HTTP client for the Wherobots REST API.
 
 ``BaseClient`` wraps a ``requests.Session`` with:
-* Auth header construction (``X-API-Key``).
+* Auth: ``X-API-Key`` when an API key is configured, otherwise the
+  workload-identity token mounted in Wherobots notebook and job pods.
 * Client attribution via the advisory ``X-Wherobots-Client`` header,
   set once on the session so every outgoing request carries it.
 * Automatic retry with exponential back-off for transient errors
@@ -20,6 +21,7 @@ from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
 from wherobots.__version__ import __version__
+from wherobots.api.workload_auth import shared_workload_identity_auth
 from wherobots.config import WherobotsConfig  # noqa: TC001
 from wherobots.exceptions import WherobotsAPIError, WherobotsConfigError
 from wherobots.utils.client_header import CLIENT_HEADER, client_header_value
@@ -35,6 +37,21 @@ _RETRIABLE_STATUS_CODES = (429, 502, 503)
 _REDIRECT_STATUS_CODES = frozenset({301, 302, 303, 307, 308})
 
 
+def json_object(response: requests.Response) -> dict[str, object]:
+    """Parse a JSON object body, or raise ``WherobotsAPIError``."""
+    try:
+        data = response.json()
+    except ValueError as exc:
+        raise WherobotsAPIError(
+            "Wherobots API returned a non-JSON body", status_code=response.status_code
+        ) from exc
+    if not isinstance(data, dict):
+        raise WherobotsAPIError(
+            "Wherobots API returned an unexpected body", status_code=response.status_code
+        )
+    return data
+
+
 class BaseClient:
     """Thin HTTP wrapper around ``requests.Session``.
 
@@ -42,8 +59,8 @@ class BaseClient:
     back-off, and unified error mapping to ``WherobotsAPIError``.
 
     Args:
-        config: A populated ``WherobotsConfig``.  Must contain at least
-            ``api_key`` and ``base_url``.
+        config: A populated ``WherobotsConfig``.  Must contain ``base_url``
+            and either ``api_key`` or ``id_token_path``.
         max_retries: Maximum number of retries for transient failures.
         backoff_factor: Multiplier for exponential back-off between
             retries.
@@ -60,10 +77,11 @@ class BaseClient:
         # session is built.
         self._closed = False
 
-        if not config.api_key or not config.api_key.strip():
+        api_key = (config.api_key or "").strip()
+        if not api_key and not config.id_token_path:
             raise WherobotsConfigError(
-                "API key required. Provide via api_key parameter or "
-                "WHEROBOTS_API_KEY environment variable."
+                "No Wherobots credentials found. Provide the api_key parameter, set "
+                "WHEROBOTS_API_KEY, or run inside a Wherobots notebook or job."
             )
 
         self._config = config
@@ -107,9 +125,14 @@ class BaseClient:
                 "Content-Type": "application/json",
                 "User-Agent": f"wherobots-python-sdk/{__version__}",
                 CLIENT_HEADER: client_header_value(config.client_chain),
-                **self._auth_headers(config.api_key),
             }
         )
+        if api_key:
+            self._session.headers.update(self._auth_headers(api_key))
+        elif config.id_token_path:
+            self._session.auth = shared_workload_identity_auth(
+                self._base_url, config.id_token_path, self._timeout
+            )
 
     @property
     def timeout(self) -> int:

wherobots/api/drive.py

@@ -21,6 +21,7 @@ from urllib.parse import quote
 
 import requests
 
+from wherobots.api.base import json_object
 from wherobots.enums import Drive, Region
 from wherobots.exceptions import (
     WherobotsAPIError,
@@ -99,21 +100,6 @@ def _encode(segments: list[str]) -> str:
     return "/".join(quote(segment, safe="") for segment in segments)
 
 
-def _json_object(response: requests.Response) -> dict[str, object]:
-    """Parse a JSON object body, or raise ``WherobotsAPIError``."""
-    try:
-        data = response.json()
-    except ValueError as exc:
-        raise WherobotsAPIError(
-            "Files API returned a non-JSON body", status_code=response.status_code
-        ) from exc
-    if not isinstance(data, dict):
-        raise WherobotsAPIError(
-            "Files API returned an unexpected body", status_code=response.status_code
-        )
-    return data
-
-
 class FilesDrive:
     """One Files drive in one region: list, create folders, transfer, rename, delete.
 
@@ -175,7 +161,7 @@ class FilesDrive:
             if cursor is not None:
                 params["cursor"] = cursor
             response = self._call("GET", route, params=params, root_listing=not route_segments)
-            page = DirectoryPage.from_dict(_json_object(response))
+            page = DirectoryPage.from_dict(json_object(response))
             entries.extend(page.entries)
             # Any cursor seen before means the server is cycling; stop rather than loop forever.
             if page.next_cursor is None or page.next_cursor in seen:
@@ -227,7 +213,7 @@ class FilesDrive:
         segments = self._required(path, directory=False)
         response = self._call("POST", self._route("file-upload-url", segments))
         try:
-            target = FileUploadTarget.from_dict(_json_object(response))
+            target = FileUploadTarget.from_dict(json_object(response))
         except ValueError as exc:
             raise WherobotsAPIError(str(exc), status_code=response.status_code) from exc
         if not target.upload_url.startswith("https://"):
@@ -350,7 +336,7 @@ class FilesDrive:
         """
         if err.status_code == _HTTP_UNAUTHORIZED:
             return WherobotsNotAuthenticatedError(
-                "The Wherobots API key was not accepted (HTTP 401)",
+                "The Wherobots API did not accept the credentials (HTTP 401)",
                 status_code=err.status_code,
                 response=err.response,
                 request_id=err.request_id,

wherobots/api/files.py

@@ -29,7 +29,11 @@ from botocore.session import Session as BotocoreSession
 
 from wherobots.api.base import BaseClient
 from wherobots.config import WherobotsConfig  # noqa: TC001
-from wherobots.exceptions import WherobotsAPIError, WherobotsValidationError
+from wherobots.exceptions import (
+    WherobotsAPIError,
+    WherobotsNotAuthenticatedError,
+    WherobotsValidationError,
+)
 from wherobots.models import StorageIntegration, TemporaryAwsCredentials
 from wherobots.utils.logger import get_logger
 
@@ -110,6 +114,9 @@ class FilesAPI:
                 "/storage/credentials",
                 json_body={"path": path, "access_mode": access_mode},
             )
+        except WherobotsNotAuthenticatedError:
+            # The workload token exchange failed before this request was sent (ADR-0003).
+            raise
         except WherobotsAPIError as exc:
             # Scrub: never let the credentials endpoint's error
             # response body bubble out — it could contain partial

wherobots/api/tasks.py

@@ -0,0 +1,265 @@
+"""Tasks — typed wrappers around the ``/tasks`` and ``/task-runs`` endpoints.
+
+A task is a named unit of work, such as RasterFlow inference, that the caller's
+organization can run. Each run is a task run, addressable by its own id, so
+``Tasks`` and ``TaskRuns`` are siblings, as they are in the API.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC
+from typing import TYPE_CHECKING
+from urllib.parse import quote
+
+from wherobots.api.base import json_object
+from wherobots.enums import Region, TaskRunState
+from wherobots.exceptions import WherobotsAPIError
+from wherobots.models import (
+    OffsetPage,
+    Task,
+    TaskRun,
+    TaskRunCost,
+    TaskRunLogs,
+    TaskRunSummary,
+    TaskSummary,
+)
+from wherobots.utils.logger import get_logger
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from datetime import datetime
+
+    from wherobots.api.base import BaseClient
+
+logger = get_logger("api.tasks")
+
+
+def _region_name(region: Region | str) -> str:
+    return region.value if isinstance(region, Region) else region
+
+
+def _region_names(regions: Region | str | Sequence[Region | str]) -> list[str]:
+    # A lone string is one region, not a sequence of one-letter regions.
+    items = [regions] if isinstance(regions, (Region, str)) else regions
+    return [_region_name(r) for r in items]
+
+
+def _state_names(states: TaskRunState | str | Sequence[TaskRunState | str]) -> list[str]:
+    items = [states] if isinstance(states, (TaskRunState, str)) else states
+    return [s.value if isinstance(s, TaskRunState) else s for s in items]
+
+
+def _task_route(task_name: str) -> str:
+    return f"/tasks/{quote(task_name, safe='')}"
+
+
+class Tasks:
+    """The tasks the caller's organization can run.
+
+    Obtain it from ``Wherobots.tasks``; do not build it directly.
+
+    Args:
+        client: The shared API connection.
+        region: Region new runs use when ``run`` is given none; ``None`` lets the
+            API apply the organization's default region.
+    """
+
+    def __init__(self, client: BaseClient, region: str | None = None) -> None:
+        """Bind to a connection and default region; see the class docstring."""
+        self._client = client
+        self._region = region
+
+    def list(
+        self,
+        *,
+        regions: Region | str | Sequence[Region | str] | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> OffsetPage[TaskSummary]:
+        """List tasks, ordered by name (``GET /tasks``).
+
+        Args:
+            regions: Only tasks that can run in this region, or in any of these regions.
+            limit: Page size, 1 to 100.
+            offset: How many matching tasks to skip.
+
+        Returns:
+            One page of tasks; ``OffsetPage.next_offset`` fetches the next.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        params: dict[str, object] = {"limit": limit, "offset": offset}
+        if regions:
+            params["regions"] = _region_names(regions)
+        response = self._client.get("/tasks", params=params)
+        return OffsetPage.from_dict(json_object(response), TaskSummary.from_dict)
+
+    def get(self, task_name: str) -> Task:
+        """Fetch a task with its input and output schemas (``GET /tasks/{name}``).
+
+        Args:
+            task_name: The task's name.
+
+        Returns:
+            The task.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        response = self._client.get(_task_route(task_name))
+        return Task.from_dict(json_object(response))
+
+    def run(
+        self,
+        task_name: str,
+        inputs: Mapping[str, object] | None = None,
+        *,
+        region: Region | str | None = None,
+        name: str | None = None,
+    ) -> TaskRunSummary:
+        """Start a run of a task (``POST /tasks/{name}/runs``).
+
+        Args:
+            task_name: The task's name.
+            inputs: Inputs matching the task's ``input_schema``.
+            region: Region to run in; defaults to the configured region, then to
+                the organization's default region.
+            name: A name for the run, shown as ``TaskRun.name``.
+
+        Returns:
+            The new run; poll ``TaskRuns.get`` with its ``task_run_id``.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures, including
+                inputs the task's schema rejects.
+        """
+        body: dict[str, object] = {"inputs": dict(inputs or {})}
+        resolved_region = _region_name(region) if region else self._region
+        if resolved_region:
+            body["region"] = resolved_region
+        if name:
+            body["name"] = name
+        logger.info("Running task '%s' in %s", task_name, resolved_region or "org default")
+        response = self._client.post(f"{_task_route(task_name)}/runs", json_body=body)
+        return TaskRunSummary.from_dict(json_object(response))
+
+
+class TaskRuns:
+    """Runs of the organization's tasks.
+
+    Obtain it from ``Wherobots.task_runs``; do not build it directly.
+
+    Args:
+        client: The shared API connection.
+    """
+
+    def __init__(self, client: BaseClient) -> None:
+        """Bind to a connection; see the class docstring."""
+        self._client = client
+
+    def list(
+        self,
+        *,
+        task_name: str | None = None,
+        states: TaskRunState | str | Sequence[TaskRunState | str] | None = None,
+        created_after: datetime | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> OffsetPage[TaskRunSummary]:
+        """List task runs, newest first (``GET /task-runs``).
+
+        Args:
+            task_name: Only runs of this task; a trailing ``*`` matches a prefix.
+            states: Only runs in this state, or in any of these states.
+            created_after: Only runs submitted after this instant; a naive
+                ``datetime`` is read as local time.
+            limit: Page size, 1 to 100.
+            offset: How many matching runs to skip.
+
+        Returns:
+            One page of runs; ``OffsetPage.next_offset`` fetches the next.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        params: dict[str, object] = {"limit": limit, "offset": offset}
+        if task_name:
+            params["taskName"] = task_name
+        if states:
+            params["state"] = _state_names(states)
+        if created_after:
+            params["createdAfter"] = created_after.astimezone(UTC).isoformat()
+        response = self._client.get("/task-runs", params=params)
+        return OffsetPage.from_dict(json_object(response), TaskRunSummary.from_dict)
+
+    def get(self, task_run_id: str) -> TaskRun:
+        """Fetch a run with its inputs and results (``GET /task-runs/{id}``).
+
+        Args:
+            task_run_id: The run's id.
+
+        Returns:
+            The run.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        response = self._client.get(self._route(task_run_id))
+        return TaskRun.from_dict(json_object(response))
+
+    def logs(self, task_run_id: str, since: str | None = None) -> TaskRunLogs:
+        """Fetch a page of a run's logs (``GET /task-runs/{id}/logs``).
+
+        Args:
+            task_run_id: The run's id.
+            since: The previous page's ``next_since``; omit for the first page.
+
+        Returns:
+            Log lines logged after ``since``.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        params = {"since": since} if since else None
+        response = self._client.get(self._route(task_run_id, "logs"), params=params)
+        return TaskRunLogs.from_dict(json_object(response))
+
+    def cost(self, task_run_id: str) -> TaskRunCost:
+        """Fetch what a run cost (``GET /task-runs/{id}/cost``).
+
+        Args:
+            task_run_id: The run's id.
+
+        Returns:
+            The run's cost; ``is_settling`` is ``True`` while it may still change.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures, or a cost the
+                SDK cannot read (rather than reporting it as zero).
+        """
+        response = self._client.get(self._route(task_run_id, "cost"))
+        try:
+            return TaskRunCost.from_dict(json_object(response))
+        except (TypeError, ValueError) as exc:
+            raise WherobotsAPIError(str(exc), status_code=response.status_code) from exc
+
+    def cancel(self, task_run_id: str) -> None:
+        """Request that a run stop (``POST /task-runs/{id}/cancel``).
+
+        The run moves to ``CANCELLING`` and then ``CANCELLED`` once the stop is
+        confirmed.
+
+        Args:
+            task_run_id: The run's id.
+
+        Raises:
+            WherobotsAPIError: On HTTP failures.
+        """
+        self._client.post(self._route(task_run_id, "cancel"))
+        logger.info("Cancel requested for task run %s", task_run_id)
+
+    @staticmethod
+    def _route(task_run_id: str, action: str | None = None) -> str:
+        route = f"/task-runs/{quote(task_run_id, safe='')}"
+        return f"{route}/{action}" if action else route

wherobots/api/workload_auth.py

@@ -0,0 +1,116 @@
+"""Workload-identity auth for code running inside Wherobots (ADR-0003).
+
+Wherobots notebook and job pods mount a workload-identity token and set
+``WHEROBOTS_ID_TOKEN_PATH`` to it. The API accepts that token as an OAuth
+refresh token at ``/ste/oauth2/token`` and returns a short-lived bearer token
+that acts as the user who launched the workload.
+"""
+
+from __future__ import annotations
+
+import functools
+import threading
+import time
+from pathlib import Path
+
+import requests
+from requests.auth import AuthBase
+
+from wherobots.exceptions import WherobotsConfigError, WherobotsNotAuthenticatedError
+
+_EXCHANGE_PATH = "/ste/oauth2/token"
+# Descriptive only: the API does not enforce scope on these tokens.
+_SCOPE = "api"
+_REFRESH_MARGIN_SECONDS = 60
+
+
+class WorkloadIdentityAuth(AuthBase):
+    """Sets ``Authorization: Bearer`` from the mounted workload-identity token.
+
+    The bearer token is cached and swapped for a new one shortly before it
+    expires, so long-running jobs keep working past its one-hour lifetime.
+
+    Args:
+        base_url: Wherobots API base URL (already validated as HTTPS).
+        id_token_path: Path to the mounted workload-identity token.
+        timeout: Timeout in seconds for the token exchange request.
+    """
+
+    def __init__(self, base_url: str, id_token_path: str, timeout: int) -> None:
+        """Build the auth; see the class docstring."""
+        self._token_url = f"{base_url}{_EXCHANGE_PATH}"
+        self._id_token_path = Path(id_token_path)
+        self._timeout = timeout
+        self._lock = threading.Lock()
+        self._access_token: str | None = None
+        self._refresh_at = 0.0
+
+    def __call__(self, request: requests.PreparedRequest) -> requests.PreparedRequest:
+        """Attach the current bearer token to *request*."""
+        request.headers["Authorization"] = f"Bearer {self._current_token()}"
+        return request
+
+    def _current_token(self) -> str:
+        with self._lock:
+            if self._access_token is None or time.monotonic() >= self._refresh_at:
+                token, expires_in = self._exchange()
+                self._access_token = token
+                self._refresh_at = time.monotonic() + max(0, expires_in - _REFRESH_MARGIN_SECONDS)
+            return self._access_token
+
+    def _exchange(self) -> tuple[str, int]:
+        try:
+            id_token = self._id_token_path.read_text(encoding="utf-8").strip()
+        except (OSError, UnicodeDecodeError) as exc:
+            raise WherobotsConfigError(
+                f"Cannot read the workload identity token at {self._id_token_path}: {exc}"
+            ) from exc
+        if not id_token:
+            raise WherobotsConfigError(
+                f"The workload identity token at {self._id_token_path} is empty"
+            )
+        # Errors carry no status_code: it would read as the status of the caller's own request.
+        try:
+            response = requests.post(
+                self._token_url,
+                data={"grant_type": "refresh_token", "refresh_token": id_token, "scope": _SCOPE},
+                timeout=self._timeout,
+                allow_redirects=False,
+            )
+            response.raise_for_status()
+            payload = response.json()
+        except requests.HTTPError as exc:
+            raise WherobotsNotAuthenticatedError(_rejection_message(exc.response)) from exc
+        except (requests.RequestException, ValueError) as exc:
+            raise WherobotsNotAuthenticatedError(
+                f"Workload identity token exchange failed: {exc}"
+            ) from exc
+
+        token = payload.get("access_token") if isinstance(payload, dict) else None
+        expires_in = payload.get("expires_in") if isinstance(payload, dict) else None
+        if not isinstance(token, str) or not isinstance(expires_in, int):
+            raise WherobotsNotAuthenticatedError(
+                "Workload identity token exchange returned an unexpected body"
+            )
+        return token, expires_in
+
+
+@functools.cache
+def shared_workload_identity_auth(
+    base_url: str, id_token_path: str, timeout: int
+) -> WorkloadIdentityAuth:
+    """Return one auth per process and token, so every client reuses one bearer token."""
+    return WorkloadIdentityAuth(base_url, id_token_path, timeout)
+
+
+def _rejection_message(response: requests.Response | None) -> str:
+    message = "Workload identity token exchange was rejected"
+    if response is None:
+        return message
+    message = f"{message} (status {response.status_code})"
+    try:
+        body = response.json()
+    except ValueError:
+        return message
+    reason = body.get("message") if isinstance(body, dict) else None
+    return f"{message}: {reason}" if isinstance(reason, str) else message

wherobots/config.py

@@ -25,6 +25,9 @@ class WherobotsConfig:
             embed this SDK (e.g. the Airflow provider). The SDK appends its
             own hop to the right of it, so the origin client stays leftmost.
             Advisory only — it never affects authentication.
+        id_token_path: Workload-identity token mounted in Wherobots notebook
+            and job pods. Used for auth only when no ``api_key`` is set
+            (ADR-0003).
     """
 
     api_key: str | None = None
@@ -35,6 +38,7 @@ class WherobotsConfig:
     version: str = "latest"
     request_timeout_seconds: int = 30
     client_chain: str | None = None
+    id_token_path: str | None = None
 
     def __repr__(self) -> str:
         """Return a string representation with the API key masked."""
@@ -54,7 +58,8 @@ class WherobotsConfig:
             f"base_url={self.base_url!r}, "
             f"version={self.version!r}, "
             f"request_timeout_seconds={self.request_timeout_seconds!r}, "
-            f"client_chain={self.client_chain!r})"
+            f"client_chain={self.client_chain!r}, "
+            f"id_token_path={self.id_token_path!r})"
         )
 
     def __post_init__(self) -> None:
@@ -90,6 +95,7 @@ class WherobotsConfig:
         version: str | None = None,
         request_timeout_seconds: int | None = None,
         client_chain: str | None = None,
+        id_token_path: str | None = None,
     ) -> WherobotsConfig:
         """Build configuration from environment variables with optional overrides.
 
@@ -108,6 +114,8 @@ class WherobotsConfig:
             client_chain: Override for ``WHEROBOTS_CLIENT_CHAIN`` — the
                 upstream ``X-Wherobots-Client`` chain this SDK appends its
                 own hop to.
+            id_token_path: Override for ``WHEROBOTS_ID_TOKEN_PATH``, which
+                Wherobots notebook and job pods set.
 
         Returns:
             A validated ``WherobotsConfig`` instance.
@@ -163,7 +171,8 @@ class WherobotsConfig:
             )
 
         return cls(
-            api_key=api_key or _env("WHEROBOTS_API_KEY"),
+            # A blank key must not hide WHEROBOTS_API_KEY behind workload identity.
+            api_key=(api_key or "").strip() or _env("WHEROBOTS_API_KEY"),
             region=region or _env("WHEROBOTS_REGION"),
             s3_bucket=s3_bucket or _env("WHEROBOTS_S3_BUCKET"),
             s3_prefix=s3_prefix or _env("WHEROBOTS_S3_PREFIX") or "wherobots-jobs",
@@ -173,4 +182,5 @@ class WherobotsConfig:
             version=version or _env("WHEROBOTS_VERSION") or "latest",
             request_timeout_seconds=timeout,
             client_chain=client_chain or _env("WHEROBOTS_CLIENT_CHAIN"),
+            id_token_path=id_token_path or _env("WHEROBOTS_ID_TOKEN_PATH"),
         )