wherobots-python-sdk 0.6.0__tar.gz → 0.7.0__tar.gz

{wherobots_python_sdk-0.6.0/wherobots_python_sdk.egg-info → wherobots_python_sdk-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wherobots-python-sdk
-Version: 0.6.0
+Version: 0.7.0
 Summary: Python SDK for Wherobots (currently covers the Jobs REST API)
 Author-email: Wherobots <support@wherobots.com>
 License-Expression: Apache-2.0
@@ -21,7 +21,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.34.2
-Requires-Dist: boto3>=1.43.108
+Requires-Dist: boto3>=1.34.0
 Dynamic: license-file
 
 # Wherobots Python SDK
@@ -118,18 +118,27 @@ job = WherobotsJob(
 
 The API key can also be set via the `WHEROBOTS_API_KEY` environment variable.
 
+Inside a Wherobots notebook or job, no API key is needed. The SDK authenticates as the user who
+launched the workload, using the token Wherobots mounts in the pod. An API key, when set, takes
+precedence.
+
+```python
+job = WherobotsJob(script="s3://bucket/script.py", name="my-job-001")
+```
+
 ## Configuration
 
 ### Environment Variables
 
 | Variable                           | Description                     | Default                              |
 |------------------------------------|---------------------------------|--------------------------------------|
-| `WHEROBOTS_API_KEY`                | API key                         | *(required)*                         |
+| `WHEROBOTS_API_KEY`                | API key                         | *(required outside Wherobots)*       |
 | `WHEROBOTS_REGION`                 | Region override (else org default) | *(none — org default)*            |
 | `WHEROBOTS_API_BASE_URL`          | API base URL                    | `https://api.cloud.wherobots.com`    |
 | `WHEROBOTS_VERSION`               | Wherobots version               | `latest`                             |
 | `WHEROBOTS_REQUEST_TIMEOUT_SECONDS`| HTTP request timeout (seconds) | `30`                                 |
 | `WHEROBOTS_CLIENT_CHAIN`           | Upstream client-attribution chain (see below) | *(none)*              |
+| `WHEROBOTS_ID_TOKEN_PATH`          | Workload identity token, set by Wherobots notebooks and jobs | *(none)* |
 
 ### WherobotsConfig
 
@@ -456,7 +465,7 @@ with wherobots.Wherobots() as wb:
 | Failure | Raised as |
 |---|---|
 | Files is not enabled for this drive in this region | `WherobotsFilesNotEnabledError` (`.drive`, `.region`) |
-| The API key was not accepted | `WherobotsNotAuthenticatedError` |
+| The credentials were not accepted | `WherobotsNotAuthenticatedError` |
 | No such file or folder | `WherobotsFileNotFoundError` |
 | Transfer to or from storage failed | `WherobotsS3Error` |
 
@@ -673,7 +682,7 @@ All exceptions inherit from `WherobotsJobError`.
 | `WherobotsS3Error`         | A transfer to or from storage failed, including Files presigned uploads and downloads. |
 | `WherobotsConfigError`     | Configuration is missing or invalid.                 |
 | `WherobotsTimeoutError`    | Job exceeded the specified timeout.                  |
-| `WherobotsNotAuthenticatedError` | Files: the API key was not accepted (HTTP 401). Subclass of `WherobotsAPIError`. |
+| `WherobotsNotAuthenticatedError` | Files: the credentials were not accepted (HTTP 401). In a Wherobots pod: the workload identity token exchange failed. Subclass of `WherobotsAPIError`. |
 | `WherobotsFilesNotEnabledError` | Files is not enabled for a drive in a region. Has `drive`, `region`. Subclass of `WherobotsAPIError`. |
 | `WherobotsFileNotFoundError` | Files: no such file or folder. Subclass of `WherobotsAPIError`. |
 

{wherobots_python_sdk-0.6.0 → wherobots_python_sdk-0.7.0}/README.md

@@ -92,18 +92,27 @@ job = WherobotsJob(
 
 The API key can also be set via the `WHEROBOTS_API_KEY` environment variable.
 
+Inside a Wherobots notebook or job, no API key is needed. The SDK authenticates as the user who
+launched the workload, using the token Wherobots mounts in the pod. An API key, when set, takes
+precedence.
+
+```python
+job = WherobotsJob(script="s3://bucket/script.py", name="my-job-001")
+```
+
 ## Configuration
 
 ### Environment Variables
 
 | Variable                           | Description                     | Default                              |
 |------------------------------------|---------------------------------|--------------------------------------|
-| `WHEROBOTS_API_KEY`                | API key                         | *(required)*                         |
+| `WHEROBOTS_API_KEY`                | API key                         | *(required outside Wherobots)*       |
 | `WHEROBOTS_REGION`                 | Region override (else org default) | *(none — org default)*            |
 | `WHEROBOTS_API_BASE_URL`          | API base URL                    | `https://api.cloud.wherobots.com`    |
 | `WHEROBOTS_VERSION`               | Wherobots version               | `latest`                             |
 | `WHEROBOTS_REQUEST_TIMEOUT_SECONDS`| HTTP request timeout (seconds) | `30`                                 |
 | `WHEROBOTS_CLIENT_CHAIN`           | Upstream client-attribution chain (see below) | *(none)*              |
+| `WHEROBOTS_ID_TOKEN_PATH`          | Workload identity token, set by Wherobots notebooks and jobs | *(none)* |
 
 ### WherobotsConfig
 
@@ -430,7 +439,7 @@ with wherobots.Wherobots() as wb:
 | Failure | Raised as |
 |---|---|
 | Files is not enabled for this drive in this region | `WherobotsFilesNotEnabledError` (`.drive`, `.region`) |
-| The API key was not accepted | `WherobotsNotAuthenticatedError` |
+| The credentials were not accepted | `WherobotsNotAuthenticatedError` |
 | No such file or folder | `WherobotsFileNotFoundError` |
 | Transfer to or from storage failed | `WherobotsS3Error` |
 
@@ -647,7 +656,7 @@ All exceptions inherit from `WherobotsJobError`.
 | `WherobotsS3Error`         | A transfer to or from storage failed, including Files presigned uploads and downloads. |
 | `WherobotsConfigError`     | Configuration is missing or invalid.                 |
 | `WherobotsTimeoutError`    | Job exceeded the specified timeout.                  |
-| `WherobotsNotAuthenticatedError` | Files: the API key was not accepted (HTTP 401). Subclass of `WherobotsAPIError`. |
+| `WherobotsNotAuthenticatedError` | Files: the credentials were not accepted (HTTP 401). In a Wherobots pod: the workload identity token exchange failed. Subclass of `WherobotsAPIError`. |
 | `WherobotsFilesNotEnabledError` | Files is not enabled for a drive in a region. Has `drive`, `region`. Subclass of `WherobotsAPIError`. |
 | `WherobotsFileNotFoundError` | Files: no such file or folder. Subclass of `WherobotsAPIError`. |
 

{wherobots_python_sdk-0.6.0 → wherobots_python_sdk-0.7.0}/pyproject.toml

@@ -25,7 +25,7 @@ classifiers = [
 keywords = ["wherobots", "spark", "sedona", "geospatial", "jobs", "sdk", "rest-api"]
 dependencies = [
     "requests>=2.34.2",
-    "boto3>=1.43.108",
+    "boto3>=1.34.0",
 ]
 
 [project.urls]
@@ -39,14 +39,14 @@ Documentation = "https://docs.wherobots.com"
 dev = [
     "pytest==9.1.1",
     "pytest-cov==7.1.0",
-    "pytest-mock==3.16.0",
-    "ruff==0.17.0",
-    "pyrefly==1.3.2",
+    "pytest-mock==3.17.0",
+    "ruff==0.17.3",
+    "pyrefly==1.4.0",
     "import-linter==2.15",
     "pre-commit==4.7.0",
-    "hypothesis==6.170.2",
+    "hypothesis==6.170.12",
     "cosmic-ray==8.7.0",
-    "ast-grep-cli==0.50.0",
+    "ast-grep-cli==0.51.0",
     "types-requests==2.33.0.20261006",
 ]
 

{wherobots_python_sdk-0.6.0 → wherobots_python_sdk-0.7.0}/tests/test_base_client.py

@@ -158,17 +158,70 @@ class TestClientAttributionHeader:
 
 
 class TestClientConfigValidation:
-    def test_missing_api_key_raises(self):
+    def test_missing_credentials_raises(self):
         cfg = WherobotsConfig(api_key=None)
-        with pytest.raises(WherobotsConfigError, match="API key required"):
+        with pytest.raises(WherobotsConfigError, match="No Wherobots credentials found"):
             BaseClient(cfg)
 
     def test_empty_api_key_raises(self):
-        cfg = WherobotsConfig(api_key="")
-        with pytest.raises(WherobotsConfigError, match="API key required"):
+        cfg = WherobotsConfig(api_key="  ")
+        with pytest.raises(WherobotsConfigError, match="No Wherobots credentials found"):
             BaseClient(cfg)
 
 
+# ---------------------------------------------------------------------------
+# Credential selection
+# ---------------------------------------------------------------------------
+
+
+class TestCredentialSelection:
+    @patch("wherobots.api.base.requests.Session")
+    def test_api_key_wins_over_workload_identity(self, MockSession):
+        session = MockSession.return_value
+        session.headers = {}
+        session.auth = None
+
+        BaseClient(
+            WherobotsConfig(
+                api_key="test-key",
+                id_token_path="/var/run/secrets/wherobots/id-token",
+                base_url="https://api.test.wherobots.com",
+            )
+        )
+
+        assert session.headers["X-API-Key"] == "test-key"
+        assert session.auth is None
+
+    @pytest.mark.parametrize("api_key", [None, "  "])
+    @patch("wherobots.api.workload_auth.requests.post")
+    @patch("requests.adapters.HTTPAdapter.send")
+    def test_workload_identity_without_api_key(self, mock_send, mock_post, api_key, tmp_path):
+        id_token = tmp_path / "id-token"
+        id_token.write_text("wid-token", encoding="utf-8")
+        exchange = MagicMock(status_code=200)
+        exchange.json.return_value = {"access_token": "access-1", "expires_in": 3600}
+        mock_post.return_value = exchange
+        api_response = requests.Response()
+        api_response.status_code = 200
+        mock_send.return_value = api_response
+
+        client = BaseClient(
+            WherobotsConfig(
+                api_key=api_key,
+                id_token_path=str(id_token),
+                base_url="https://api.test.wherobots.com/",
+                request_timeout_seconds=12,
+            )
+        )
+        client.get("/runs")
+
+        sent = mock_send.call_args.args[0]
+        assert sent.headers["Authorization"] == "Bearer access-1"
+        assert "X-API-Key" not in sent.headers
+        assert mock_post.call_args.args == ("https://api.test.wherobots.com/ste/oauth2/token",)
+        assert mock_post.call_args.kwargs["timeout"] == 12
+
+
 # ---------------------------------------------------------------------------
 # Request error wrapping
 # ---------------------------------------------------------------------------

{wherobots_python_sdk-0.6.0 → wherobots_python_sdk-0.7.0}/tests/test_config.py

@@ -88,6 +88,7 @@ class TestFromEnv:
             "WHEROBOTS_VERSION",
             "WHEROBOTS_REQUEST_TIMEOUT_SECONDS",
             "WHEROBOTS_CLIENT_CHAIN",
+            "WHEROBOTS_ID_TOKEN_PATH",
         ]:
             monkeypatch.delenv(var, raising=False)
 
@@ -100,6 +101,7 @@ class TestFromEnv:
         assert cfg.version == "latest"
         assert cfg.request_timeout_seconds == 30
         assert cfg.client_chain is None
+        assert cfg.id_token_path is None
 
     def test_from_env_timeout_override(self, monkeypatch):
         monkeypatch.delenv("WHEROBOTS_REQUEST_TIMEOUT_SECONDS", raising=False)
@@ -116,6 +118,16 @@ class TestFromEnv:
         cfg = WherobotsConfig.from_env(client_chain="client=mcp;ver=0.9")
         assert cfg.client_chain == "client=mcp;ver=0.9"
 
+    def test_blank_explicit_api_key_falls_back_to_env(self, monkeypatch):
+        monkeypatch.setenv("WHEROBOTS_API_KEY", "env-key")
+        cfg = WherobotsConfig.from_env(api_key="  ")
+        assert cfg.api_key == "env-key"
+
+    def test_id_token_path_from_env(self, monkeypatch):
+        monkeypatch.setenv("WHEROBOTS_ID_TOKEN_PATH", "/var/run/secrets/wherobots/id-token")
+        cfg = WherobotsConfig.from_env()
+        assert cfg.id_token_path == "/var/run/secrets/wherobots/id-token"
+
 
 # ---------------------------------------------------------------------------
 # Frozen

{wherobots_python_sdk-0.6.0 → wherobots_python_sdk-0.7.0}/tests/test_files_api.py

@@ -14,7 +14,11 @@ from wherobots.api.files import (
     _validate_filename,
 )
 from wherobots.config import WherobotsConfig
-from wherobots.exceptions import WherobotsAPIError, WherobotsValidationError
+from wherobots.exceptions import (
+    WherobotsAPIError,
+    WherobotsNotAuthenticatedError,
+    WherobotsValidationError,
+)
 from wherobots.models import StorageIntegration, TemporaryAwsCredentials
 
 # ---------------------------------------------------------------------------
@@ -110,6 +114,15 @@ class TestGetStorageCredentials:
         with pytest.raises(WherobotsAPIError, match="Invalid JSON"):
             api.get_storage_credentials("s3://x/y")
 
+    def test_workload_token_exchange_failure_passes_through(self, files_api):
+        api, session = files_api
+        session.request.side_effect = WherobotsNotAuthenticatedError(
+            "Workload identity token exchange was rejected (status 401): Session is expired"
+        )
+
+        with pytest.raises(WherobotsNotAuthenticatedError, match="Session is expired"):
+            api.get_storage_credentials("s3://x/y")
+
     def test_default_access_mode_is_read(self, files_api, creds_payload):
         """Least-privilege default: public callers get read-only creds unless
         they explicitly opt into read_write. The SDK's upload paths pass

wherobots_python_sdk-0.7.0/tests/test_workload_auth.py

@@ -0,0 +1,151 @@
+"""Tests for WorkloadIdentityAuth: token exchange, caching, refresh, errors."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+import requests
+
+from wherobots.api.workload_auth import WorkloadIdentityAuth, shared_workload_identity_auth
+from wherobots.exceptions import WherobotsConfigError, WherobotsNotAuthenticatedError
+
+BASE_URL = "https://api.test.wherobots.com"
+
+
+@pytest.fixture
+def id_token_file(tmp_path):
+    path = tmp_path / "id-token"
+    path.write_text("wid-token\n", encoding="utf-8")
+    return path
+
+
+def _token_response(access_token, expires_in=3600):
+    response = MagicMock()
+    response.status_code = 200
+    response.raise_for_status.return_value = None
+    response.json.return_value = {
+        "access_token": access_token,
+        "expires_in": expires_in,
+        "token_type": "Bearer",
+    }
+    return response
+
+
+def _authorize(auth):
+    request = requests.Request("GET", f"{BASE_URL}/runs").prepare()
+    return auth(request).headers["Authorization"]
+
+
+@patch("wherobots.api.workload_auth.requests.post")
+def test_exchanges_the_mounted_token_for_a_bearer(mock_post, id_token_file):
+    mock_post.return_value = _token_response("access-1")
+    auth = WorkloadIdentityAuth(BASE_URL, str(id_token_file), timeout=30)
+
+    assert _authorize(auth) == "Bearer access-1"
+    mock_post.assert_called_once_with(
+        f"{BASE_URL}/ste/oauth2/token",
+        data={"grant_type": "refresh_token", "refresh_token": "wid-token", "scope": "api"},
+        timeout=30,
+        allow_redirects=False,
+    )
+
+
+@patch("wherobots.api.workload_auth.time.monotonic")
+@patch("wherobots.api.workload_auth.requests.post")
+def test_reuses_the_token_until_shortly_before_expiry(mock_post, mock_clock, id_token_file):
+    mock_post.side_effect = [_token_response("access-1"), _token_response("access-2")]
+    auth = WorkloadIdentityAuth(BASE_URL, str(id_token_file), timeout=30)
+
+    mock_clock.return_value = 1000.0
+    assert _authorize(auth) == "Bearer access-1"
+    mock_clock.return_value = 1000.0 + 3600 - 61
+    assert _authorize(auth) == "Bearer access-1"
+    mock_clock.return_value = 1000.0 + 3600 - 60
+    assert _authorize(auth) == "Bearer access-2"
+    assert mock_post.call_count == 2
+
+
+@patch("wherobots.api.workload_auth.time.monotonic")
+@patch("wherobots.api.workload_auth.requests.post")
+def test_refresh_rereads_the_token_file(mock_post, mock_clock, id_token_file):
+    mock_post.side_effect = [_token_response("access-1"), _token_response("access-2")]
+    auth = WorkloadIdentityAuth(BASE_URL, str(id_token_file), timeout=30)
+
+    mock_clock.return_value = 0.0
+    _authorize(auth)
+    id_token_file.write_text("rotated-wid", encoding="utf-8")
+    mock_clock.return_value = 3600.0
+    _authorize(auth)
+
+    assert mock_post.call_args.kwargs["data"]["refresh_token"] == "rotated-wid"
+
+
+def test_missing_token_file_raises_config_error(tmp_path):
+    auth = WorkloadIdentityAuth(BASE_URL, str(tmp_path / "missing"), timeout=30)
+
+    with pytest.raises(WherobotsConfigError, match="Cannot read the workload identity token"):
+        _authorize(auth)
+
+
+def test_undecodable_token_file_raises_config_error(tmp_path):
+    path = tmp_path / "id-token"
+    path.write_bytes(b"\xff\xfe")
+    auth = WorkloadIdentityAuth(BASE_URL, str(path), timeout=30)
+
+    with pytest.raises(WherobotsConfigError, match="Cannot read the workload identity token"):
+        _authorize(auth)
+
+
+@patch("wherobots.api.workload_auth.requests.post")
+def test_empty_token_file_raises_config_error(mock_post, tmp_path):
+    path = tmp_path / "id-token"
+    path.write_text("\n", encoding="utf-8")
+    auth = WorkloadIdentityAuth(BASE_URL, str(path), timeout=30)
+
+    with pytest.raises(WherobotsConfigError, match="is empty"):
+        _authorize(auth)
+    mock_post.assert_not_called()
+
+
+@patch("wherobots.api.workload_auth.requests.post")
+def test_rejected_exchange_carries_the_server_reason(mock_post, id_token_file):
+    response = MagicMock()
+    response.status_code = 401
+    response.json.return_value = {"message": "Session is expired"}
+    response.raise_for_status.side_effect = requests.HTTPError(response=response)
+    mock_post.return_value = response
+    auth = WorkloadIdentityAuth(BASE_URL, str(id_token_file), timeout=30)
+
+    with pytest.raises(WherobotsNotAuthenticatedError) as exc_info:
+        _authorize(auth)
+    assert str(exc_info.value) == (
+        "Workload identity token exchange was rejected (status 401): Session is expired"
+    )
+    # The status belongs to the exchange, not to the request being authenticated.
+    assert exc_info.value.status_code is None
+
+
+@patch("wherobots.api.workload_auth.requests.post")
+def test_connection_failure_raises_not_authenticated(mock_post, id_token_file):
+    mock_post.side_effect = requests.ConnectionError("unreachable")
+    auth = WorkloadIdentityAuth(BASE_URL, str(id_token_file), timeout=30)
+
+    with pytest.raises(WherobotsNotAuthenticatedError, match="unreachable"):
+        _authorize(auth)
+
+
+@patch("wherobots.api.workload_auth.requests.post")
+def test_unexpected_body_raises_not_authenticated(mock_post, id_token_file):
+    response = _token_response("access-1")
+    response.json.return_value = {"access_token": "access-1"}
+    mock_post.return_value = response
+    auth = WorkloadIdentityAuth(BASE_URL, str(id_token_file), timeout=30)
+
+    with pytest.raises(WherobotsNotAuthenticatedError, match="unexpected body"):
+        _authorize(auth)
+
+
+def test_shared_auth_is_one_instance_per_token(tmp_path):
+    first = shared_workload_identity_auth(BASE_URL, str(tmp_path / "a"), 30)
+
+    assert shared_workload_identity_auth(BASE_URL, str(tmp_path / "a"), 30) is first
+    assert shared_workload_identity_auth(BASE_URL, str(tmp_path / "b"), 30) is not first

{wherobots_python_sdk-0.6.0 → wherobots_python_sdk-0.7.0}/wherobots/__version__.py

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

{wherobots_python_sdk-0.6.0 → wherobots_python_sdk-0.7.0}/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
@@ -57,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.
@@ -75,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
@@ -122,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_python_sdk-0.6.0 → wherobots_python_sdk-0.7.0}/wherobots/api/drive.py

@@ -336,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_python_sdk-0.6.0 → wherobots_python_sdk-0.7.0}/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_python_sdk-0.7.0/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_python_sdk-0.6.0 → wherobots_python_sdk-0.7.0}/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"),
         )

{wherobots_python_sdk-0.6.0 → wherobots_python_sdk-0.7.0}/wherobots/exceptions.py

@@ -48,7 +48,7 @@ class WherobotsTimeoutError(WherobotsJobError):
 
 
 class WherobotsNotAuthenticatedError(WherobotsAPIError):
-    """Raised when the Wherobots API does not accept the API key (HTTP 401)."""
+    """Raised when the Wherobots API does not accept the credentials."""
 
 
 class WherobotsFileNotFoundError(WherobotsAPIError):

{wherobots_python_sdk-0.6.0 → wherobots_python_sdk-0.7.0/wherobots_python_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wherobots-python-sdk
-Version: 0.6.0
+Version: 0.7.0
 Summary: Python SDK for Wherobots (currently covers the Jobs REST API)
 Author-email: Wherobots <support@wherobots.com>
 License-Expression: Apache-2.0
@@ -21,7 +21,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.34.2
-Requires-Dist: boto3>=1.43.108
+Requires-Dist: boto3>=1.34.0
 Dynamic: license-file
 
 # Wherobots Python SDK
@@ -118,18 +118,27 @@ job = WherobotsJob(
 
 The API key can also be set via the `WHEROBOTS_API_KEY` environment variable.
 
+Inside a Wherobots notebook or job, no API key is needed. The SDK authenticates as the user who
+launched the workload, using the token Wherobots mounts in the pod. An API key, when set, takes
+precedence.
+
+```python
+job = WherobotsJob(script="s3://bucket/script.py", name="my-job-001")
+```
+
 ## Configuration
 
 ### Environment Variables
 
 | Variable                           | Description                     | Default                              |
 |------------------------------------|---------------------------------|--------------------------------------|
-| `WHEROBOTS_API_KEY`                | API key                         | *(required)*                         |
+| `WHEROBOTS_API_KEY`                | API key                         | *(required outside Wherobots)*       |
 | `WHEROBOTS_REGION`                 | Region override (else org default) | *(none — org default)*            |
 | `WHEROBOTS_API_BASE_URL`          | API base URL                    | `https://api.cloud.wherobots.com`    |
 | `WHEROBOTS_VERSION`               | Wherobots version               | `latest`                             |
 | `WHEROBOTS_REQUEST_TIMEOUT_SECONDS`| HTTP request timeout (seconds) | `30`                                 |
 | `WHEROBOTS_CLIENT_CHAIN`           | Upstream client-attribution chain (see below) | *(none)*              |
+| `WHEROBOTS_ID_TOKEN_PATH`          | Workload identity token, set by Wherobots notebooks and jobs | *(none)* |
 
 ### WherobotsConfig
 
@@ -456,7 +465,7 @@ with wherobots.Wherobots() as wb:
 | Failure | Raised as |
 |---|---|
 | Files is not enabled for this drive in this region | `WherobotsFilesNotEnabledError` (`.drive`, `.region`) |
-| The API key was not accepted | `WherobotsNotAuthenticatedError` |
+| The credentials were not accepted | `WherobotsNotAuthenticatedError` |
 | No such file or folder | `WherobotsFileNotFoundError` |
 | Transfer to or from storage failed | `WherobotsS3Error` |
 
@@ -673,7 +682,7 @@ All exceptions inherit from `WherobotsJobError`.
 | `WherobotsS3Error`         | A transfer to or from storage failed, including Files presigned uploads and downloads. |
 | `WherobotsConfigError`     | Configuration is missing or invalid.                 |
 | `WherobotsTimeoutError`    | Job exceeded the specified timeout.                  |
-| `WherobotsNotAuthenticatedError` | Files: the API key was not accepted (HTTP 401). Subclass of `WherobotsAPIError`. |
+| `WherobotsNotAuthenticatedError` | Files: the credentials were not accepted (HTTP 401). In a Wherobots pod: the workload identity token exchange failed. Subclass of `WherobotsAPIError`. |
 | `WherobotsFilesNotEnabledError` | Files is not enabled for a drive in a region. Has `drive`, `region`. Subclass of `WherobotsAPIError`. |
 | `WherobotsFileNotFoundError` | Files: no such file or folder. Subclass of `WherobotsAPIError`. |
 

{wherobots_python_sdk-0.6.0 → wherobots_python_sdk-0.7.0}/wherobots_python_sdk.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ tests/test_regressions.py
 tests/test_security.py
 tests/test_tasks.py
 tests/test_utils.py
+tests/test_workload_auth.py
 wherobots/__init__.py
 wherobots/__version__.py
 wherobots/client.py
@@ -33,6 +34,7 @@ wherobots/api/drive.py
 wherobots/api/files.py
 wherobots/api/runs.py
 wherobots/api/tasks.py
+wherobots/api/workload_auth.py
 wherobots/utils/__init__.py
 wherobots/utils/client_header.py
 wherobots/utils/logger.py

{wherobots_python_sdk-0.6.0 → wherobots_python_sdk-0.7.0}/wherobots_python_sdk.egg-info/requires.txt

@@ -1,2 +1,2 @@
 requests>=2.34.2
-boto3>=1.43.108
+boto3>=1.34.0