Use SecretStr for API key and access token + Config follow up fixes (#112)

andhus · claude · web-flow · commit 65a214525ccd · 2026-04-05T23:44:32.000+02:00
## Summary

- **SecretStr for credentials**: `RegistryAuth.api_key` and `RegistryAuth.access_token` use Pydantic `SecretStr` — masked as `**********` in repr/logs/model_dump
- **`STARDAG_API_URL`**: Replaces `STARDAG_REGISTRY_URL` as canonical env var (consistent with `STARDAG_API_KEY`, `STARDAG_API_TIMEOUT`). Old name still works with deprecation warning
- **Fix: env var override + token auth**: When `STARDAG_API_URL` overrides URL/workspace/environment, user and registry_name are now inherited from the active profile so OIDC token refresh still works
- Updated all docs, examples, CLI help, integration tests

---------

Co-authored-by: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.claude/skills/stardag/registry-and-platform.md b/.claude/skills/stardag/registry-and-platform.md
@@ -44,7 +44,7 @@ The SDK communicates with the API via `APIRegistry`:
 import stardag as sd
 
 # Option 1: Environment variables
-# STARDAG_REGISTRY_URL=https://api.stardag.com
+# STARDAG_API_URL=https://api.stardag.com
 # STARDAG_API_KEY=sk_...
 # STARDAG_WORKSPACE_ID=...
 
@@ -162,7 +162,7 @@ stardag modal stardag-api-key create        # Create API key for Modal
 | Variable                 | Purpose                   |
 | ------------------------ | ------------------------- |
 | `STARDAG_PROFILE`        | Active profile name       |
-| `STARDAG_REGISTRY_URL`   | Registry API URL          |
+| `STARDAG_API_URL`        | Registry API URL          |
 | `STARDAG_WORKSPACE_ID`   | Workspace UUID            |
 | `STARDAG_ENVIRONMENT_ID` | Environment UUID          |
 | `STARDAG_API_KEY`        | API key (`sk_...`)        |
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,19 @@ For detailed SDK migration guides, see [RELEASE_NOTES.md](RELEASE_NOTES.md).
 
 ## [Unreleased]
 
+## [0.5.3] — 2026-04-05
+
+### SDK
+
+#### Security
+
+- **Secret masking**: `RegistryAuth.api_key` and `RegistryAuth.access_token` now use Pydantic `SecretStr`. Values are masked as `**********` in `repr()`, `str()`, `model_dump()`, and log output, preventing accidental leakage of credentials.
+- **`STARDAG_API_URL` env var**: Replaces `STARDAG_REGISTRY_URL` as the canonical env var for the registry API URL. `STARDAG_REGISTRY_URL` still works as a deprecated alias with a warning. Consistent with `STARDAG_API_KEY` and `STARDAG_API_TIMEOUT`.
+
+#### Bug fixes
+
+- **Token auth with env var overrides**: When `STARDAG_API_URL` is set (bypassing profile for URL/workspace/environment), the loader now inherits user and registry_name from the active profile so that OIDC token auth still works.
+
 ## [0.5.2] — 2026-04-05
 
 ### SDK
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -6,6 +6,38 @@ For changes to the Registry API, UI, and other components, see [CHANGELOG.md](CH
 
 ---
 
+## v0.5.3 — Secret masking for auth credentials
+
+`RegistryAuth.api_key` and `RegistryAuth.access_token` now use Pydantic
+`SecretStr` instead of plain `str`. This means secrets are automatically masked
+as `**********` in `repr()`, `str()`, `model_dump()`, and log output.
+
+**Migration**: If you read these fields directly, call `.get_secret_value()`
+to get the plain string:
+
+```python
+config = get_config()
+if config.registry and config.registry.auth.api_key:
+    key = config.registry.auth.api_key.get_secret_value()
+```
+
+Truthiness checks still work (`if config.registry.auth.api_key:` is fine).
+
+### Env var rename: `STARDAG_API_URL`
+
+`STARDAG_REGISTRY_URL` is renamed to `STARDAG_API_URL` for consistency with
+`STARDAG_API_KEY` and `STARDAG_API_TIMEOUT`. The old name still works as a
+deprecated alias (with a `DeprecationWarning`).
+
+### Bug fix: token auth with env var overrides
+
+When `STARDAG_API_URL`/`STARDAG_WORKSPACE_ID`/`STARDAG_ENVIRONMENT_ID` are
+set directly (bypassing profile for connection details), the loader now still
+inherits user and registry_name from the active profile. This fixes OIDC token
+auth failing in setups that override the URL but rely on a profile for identity.
+
+---
+
 ## v0.5.2 — Configuration cleanup and auth token auto-refresh
 
 This release restructures the configuration system and adds automatic JWT token
diff --git a/docs/docs/configuration/cli.md b/docs/docs/configuration/cli.md
@@ -347,7 +347,7 @@ All CLI behavior can be overridden with environment variables:
 | Variable                     | Description                   |
 | ---------------------------- | ----------------------------- |
 | `STARDAG_PROFILE`            | Active profile name           |
-| `STARDAG_REGISTRY_URL`       | Registry API URL              |
+| `STARDAG_API_URL`            | Registry API URL              |
 | `STARDAG_API_KEY`            | API key (bypasses OAuth)      |
 | `STARDAG_WORKSPACE_ID`       | Workspace UUID                |
 | `STARDAG_ENVIRONMENT_ID`     | Environment UUID              |
@@ -436,7 +436,7 @@ All CLI behavior can be overridden with environment variables:
 
 ```sh
 # No interactive login needed - use API key
-export STARDAG_REGISTRY_URL=https://api.stardag.com
+export STARDAG_API_URL=https://api.stardag.com
 export STARDAG_API_KEY=sk_...
 export STARDAG_WORKSPACE_ID=...
 export STARDAG_ENVIRONMENT_ID=...
diff --git a/docs/docs/configuration/index.md b/docs/docs/configuration/index.md
@@ -87,7 +87,7 @@ Then configure:
 ### Production (CI/CD)
 
 ```sh
-export STARDAG_REGISTRY_URL=https://api.stardag.com
+export STARDAG_API_URL=https://api.stardag.com
 export STARDAG_API_KEY=sk_...
 export STARDAG_WORKSPACE_ID=...
 export STARDAG_ENVIRONMENT_ID=...
diff --git a/docs/docs/configuration/profiles.md b/docs/docs/configuration/profiles.md
@@ -175,7 +175,7 @@ Environment variables override profile settings:
 | Variable                 | Description                        |
 | ------------------------ | ---------------------------------- |
 | `STARDAG_PROFILE`        | Active profile name                |
-| `STARDAG_REGISTRY_URL`   | Registry URL (overrides profile)   |
+| `STARDAG_API_URL`        | Registry URL (overrides profile)   |
 | `STARDAG_API_KEY`        | API key for authentication         |
 | `STARDAG_WORKSPACE_ID`   | Workspace ID (overrides profile)   |
 | `STARDAG_ENVIRONMENT_ID` | Environment ID (overrides profile) |
diff --git a/docs/docs/how-to/use-api-registry.md b/docs/docs/how-to/use-api-registry.md
@@ -24,7 +24,7 @@ The API Registry:
 
 ```sh
 export STARDAG_API_KEY=sk_your_api_key_here
-export STARDAG_REGISTRY_URL=https://api.stardag.com
+export STARDAG_API_URL=https://api.stardag.com
 export STARDAG_WORKSPACE_ID=your-workspace-id
 ```
 
@@ -57,7 +57,7 @@ sd.build(my_task, registry=registry)
 ### Via Environment Variables
 
 ```sh
-export STARDAG_REGISTRY_URL=https://api.stardag.com
+export STARDAG_API_URL=https://api.stardag.com
 export STARDAG_WORKSPACE_ID=workspace-uuid
 export STARDAG_API_KEY=sk_...
 ```
diff --git a/integration-tests/tests/test_cli.py b/integration-tests/tests/test_cli.py
@@ -173,11 +173,11 @@ def test_registry_url_from_env(
         self,
         docker_services: ServiceEndpoints,
     ) -> None:
-        """Test that STARDAG_REGISTRY_URL is respected."""
+        """Test that STARDAG_API_URL is respected."""
         with tempfile.TemporaryDirectory() as tmpdir:
             env = {
                 "HOME": tmpdir,
-                "STARDAG_REGISTRY_URL": docker_services.api,
+                "STARDAG_API_URL": docker_services.api,
             }
             result = run_stardag_cli("config", "show", env=env)
             assert result.returncode == 0
@@ -196,7 +196,7 @@ def test_config_with_multiple_env_vars(
         with tempfile.TemporaryDirectory() as tmpdir:
             env = {
                 "HOME": tmpdir,
-                "STARDAG_REGISTRY_URL": docker_services.api,
+                "STARDAG_API_URL": docker_services.api,
                 "STARDAG_WORKSPACE_ID": test_workspace_id,
                 "STARDAG_ENVIRONMENT_ID": test_environment_id,
             }
diff --git a/lib/stardag-examples/src/stardag_examples/benchmarks/README.md b/lib/stardag-examples/src/stardag_examples/benchmarks/README.md
@@ -19,7 +19,7 @@ STARDAG_API_KEY=<key> uv run python -m stardag_examples.benchmarks.run_benchmark
 # With local registry and global concurrency locks enabled
 STARDAG_API_KEY=<key> uv run python -m stardag_examples.benchmarks.run_benchmark --registry local --lock
 
-# With remote registry (uses STARDAG_REGISTRY_URL from env/config)
+# With remote registry (uses STARDAG_API_URL from env/config)
 uv run python -m stardag_examples.benchmarks.run_benchmark --registry remote
 ```
 
diff --git a/lib/stardag-examples/src/stardag_examples/benchmarks/run_benchmark.py b/lib/stardag-examples/src/stardag_examples/benchmarks/run_benchmark.py
@@ -292,7 +292,7 @@ def parse_args() -> argparse.Namespace:
   # Run with local registry and global locks enabled:
   STARDAG_API_KEY=<key> uv run python -m stardag_examples.benchmarks.run_benchmark --registry local --lock
 
-  # Run with remote registry (uses STARDAG_REGISTRY_URL env var):
+  # Run with remote registry (uses STARDAG_API_URL env var):
   uv run python -m stardag_examples.benchmarks.run_benchmark --registry remote
 
 Authentication:
diff --git a/lib/stardag/src/stardag/_cli/__init__.py b/lib/stardag/src/stardag/_cli/__init__.py
@@ -30,7 +30,7 @@
 
 Configuration:
     Set STARDAG_PROFILE=<profile-name> to use a specific profile.
-    Set STARDAG_REGISTRY_URL, STARDAG_WORKSPACE_ID, STARDAG_ENVIRONMENT_ID
+    Set STARDAG_API_URL, STARDAG_WORKSPACE_ID, STARDAG_ENVIRONMENT_ID
     for direct configuration (bypasses profiles).
     Set STARDAG_API_KEY for API key authentication.
 """
diff --git a/lib/stardag/src/stardag/_cli/config.py b/lib/stardag/src/stardag/_cli/config.py
@@ -96,8 +96,9 @@ def show_config() -> None:
     if has_api_key:
         typer.echo("  Method: API Key")
     elif reg and reg.auth.access_token:
+        token_val = reg.auth.access_token.get_secret_value()
         typer.echo("  Method: JWT")
-        typer.echo(f"  Token: {reg.auth.access_token[:20]}...")
+        typer.echo(f"  Token: {token_val[:20]}...")
     else:
         typer.echo("  Method: Not authenticated")
 
diff --git a/lib/stardag/src/stardag/_cli/modal.py b/lib/stardag/src/stardag/_cli/modal.py
@@ -95,7 +95,7 @@ def _print_stardag_context(
     """Print stardag context info (registry, workspace, environment, target roots)."""
     import json
 
-    registry = env_vars.get("STARDAG_REGISTRY_URL", "none (local mode)")
+    registry = env_vars.get("STARDAG_API_URL", "none (local mode)")
     ws_id = env_vars.get("STARDAG_WORKSPACE_ID", "N/A")
     env_id = env_vars.get("STARDAG_ENVIRONMENT_ID", "N/A")
 
diff --git a/lib/stardag/src/stardag/config/__init__.py b/lib/stardag/src/stardag/config/__init__.py
@@ -21,7 +21,8 @@
 
 Environment Variables (highest priority):
     STARDAG_PROFILE          - Profile name to use (looks up in config.toml)
-    STARDAG_REGISTRY_URL     - Direct registry URL override
+    STARDAG_API_URL          - Registry API URL override
+    STARDAG_REGISTRY_URL     - Deprecated alias for STARDAG_API_URL
     STARDAG_WORKSPACE_ID     - Direct workspace ID override
     STARDAG_ENVIRONMENT_ID   - Direct environment ID override
     STARDAG_API_KEY          - API key for authentication
diff --git a/lib/stardag/src/stardag/config/loader.py b/lib/stardag/src/stardag/config/loader.py
@@ -7,6 +7,8 @@
 import os
 from typing import Any
 
+from pydantic import SecretStr
+
 from stardag.config.cache import (
     _looks_like_uuid,
     get_cached_environment_id,
@@ -149,11 +151,34 @@ def load_config(
     workspace_id: str | None = None
     environment_id: str | None = None
 
+    # Resolve API URL: STARDAG_API_URL (canonical) or STARDAG_REGISTRY_URL (deprecated)
+    explicit_url = env_settings.api_url
+    if not explicit_url:
+        legacy_url = os.environ.get("STARDAG_REGISTRY_URL")
+        if legacy_url:
+            import warnings
+
+            warnings.warn(
+                "STARDAG_REGISTRY_URL is deprecated, use STARDAG_API_URL instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            explicit_url = legacy_url
+
     # Check for direct env var overrides first
-    if env_settings.registry_url:
-        registry_url = env_settings.registry_url
+    if explicit_url:
+        registry_url = explicit_url
         workspace_id = env_settings.workspace_id
         environment_id = env_settings.environment_id
+        # Even with direct env var overrides, try to inherit user/registry_name
+        # from the active profile so that token auth (OIDC refresh) still works.
+        _profile_name = env_settings.profile or toml_config.default.get("profile")
+        if _profile_name:
+            _profile = toml_config.profile.get(_profile_name)
+            if _profile:
+                profile_name = _profile_name
+                registry_name = _profile.registry
+                user = _profile.user
     # Then check for profile-based config
     elif env_settings.profile:
         profile_name = env_settings.profile
@@ -268,7 +293,10 @@ def load_config(
                 pass
 
     # 6. Get API key from env
-    api_key = env_settings.api_key or os.environ.get("STARDAG_API_KEY")
+    api_key_raw = os.environ.get("STARDAG_API_KEY")
+    api_key: SecretStr | None = env_settings.api_key or (
+        SecretStr(api_key_raw) if api_key_raw else None
+    )
 
     # 7. Build canonical RegistryConfig (or None for offline mode)
     registry_cfg: RegistryConfig | None = None
@@ -280,7 +308,7 @@ def load_config(
             auth=RegistryAuth(
                 api_key=api_key,
                 user_email=user,
-                access_token=access_token,
+                access_token=SecretStr(access_token) if access_token else None,
             ),
             timeout=env_settings.api_timeout or DEFAULT_API_TIMEOUT,
         )
diff --git a/lib/stardag/src/stardag/config/models.py b/lib/stardag/src/stardag/config/models.py
@@ -5,7 +5,7 @@
 import os
 from typing import Annotated, Any
 
-from pydantic import AfterValidator, BaseModel, Field
+from pydantic import AfterValidator, BaseModel, Field, SecretStr
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from stardag.config.paths import (
@@ -115,15 +115,19 @@ class TargetConfig(BaseModel):
 class RegistryAuth(BaseModel):
     """Authentication configuration for the registry.
 
+    ``api_key`` and ``access_token`` use ``SecretStr`` so they are masked
+    in ``repr()``, ``str()``, and ``model_dump()`` by default — preventing
+    accidental leakage in logs or error messages.
+
     Attributes:
         api_key: API key for authentication (production/CI).
         user_email: User identifier (email) for OIDC credential lookup + refresh.
         access_token: JWT access token from browser login (local dev).
     """
 
-    api_key: str | None = None
+    api_key: SecretStr | None = None
     user_email: str | None = None
-    access_token: str | None = None
+    access_token: SecretStr | None = None
 
 
 class RegistryConfig(BaseModel):
@@ -184,15 +188,15 @@ class StardagSettings(BaseSettings):
     profile: str | None = None
 
     # Direct overrides (bypass profile)
-    registry_url: str | None = None
+    api_url: str | None = None  # STARDAG_API_URL (canonical)
     workspace_id: str | None = None
     environment_id: str | None = None
 
     # API settings
     api_timeout: float | None = None
 
     # API key
-    api_key: str | None = None
+    api_key: SecretStr | None = None
 
     # Force no registry (offline/local mode)
     no_registry: bool = False
diff --git a/lib/stardag/src/stardag/integration/modal/_app.py b/lib/stardag/src/stardag/integration/modal/_app.py
@@ -84,7 +84,7 @@ def get_profile_env_vars(profile: str | None = None) -> dict[str, str]:
 
     Returns:
         Dict of environment variables to inject into Modal functions:
-        - STARDAG_REGISTRY_URL: API endpoint
+        - STARDAG_API_URL: API endpoint
         - STARDAG_WORKSPACE_ID: Workspace UUID
         - STARDAG_ENVIRONMENT_ID: Environment UUID
         - STARDAG_TARGET_ROOTS: JSON dict of target roots (pydantic-settings parses this)
@@ -94,7 +94,7 @@ def get_profile_env_vars(profile: str | None = None) -> dict[str, str]:
         >>> env_vars = get_profile_env_vars("production")
         >>> print(env_vars)
         {
-            'STARDAG_REGISTRY_URL': 'https://api.stardag.com',
+            'STARDAG_API_URL': 'https://api.stardag.com',
             'STARDAG_WORKSPACE_ID': '...',
             'STARDAG_ENVIRONMENT_ID': '...',
             'STARDAG_TARGET_ROOTS': '{"default": "s3://bucket/prefix"}',
@@ -122,7 +122,7 @@ def get_profile_env_vars(profile: str | None = None) -> dict[str, str]:
 
     reg = config.registry
     if reg:
-        env_vars["STARDAG_REGISTRY_URL"] = reg.url
+        env_vars["STARDAG_API_URL"] = reg.url
         if reg.workspace_id:
             env_vars["STARDAG_WORKSPACE_ID"] = reg.workspace_id
         if reg.environment_id:
diff --git a/lib/stardag/src/stardag/registry/_api_registry.py b/lib/stardag/src/stardag/registry/_api_registry.py
@@ -84,7 +84,7 @@ def __init__(
         if not resolved_url:
             raise ValueError(
                 "APIRegistry requires a registry URL. "
-                "Set STARDAG_REGISTRY_URL or configure a profile with a registry."
+                "Set STARDAG_API_URL or configure a profile with a registry."
             )
         self.api_url = resolved_url.rstrip("/")
 
@@ -99,15 +99,17 @@ def __init__(
         self.environment_id = environment_id or (reg.environment_id if reg else None)
 
         # Build auth object
-        resolved_api_key = api_key or (reg.auth.api_key if reg else None)
+        resolved_api_key = api_key or (
+            reg.auth.api_key.get_secret_value() if reg and reg.auth.api_key else None
+        )
         if resolved_api_key:
             self._auth: httpx.Auth = StardagAPIKeyAuth(resolved_api_key)
             logger.debug("APIRegistry initialized with API key authentication")
         elif reg and reg.auth.access_token:
             # registry_name is optional — StardagTokenAuth can derive a
             # credential key from the URL when no profile is configured.
             self._auth = StardagTokenAuth(
-                access_token=reg.auth.access_token,
+                access_token=reg.auth.access_token.get_secret_value(),
                 workspace_id=reg.workspace_id,
                 user_email=reg.auth.user_email,
                 registry_url=reg.url,
diff --git a/lib/stardag/src/stardag/registry/_http_client.py b/lib/stardag/src/stardag/registry/_http_client.py
diff --git a/lib/stardag/tests/test_config.py b/lib/stardag/tests/test_config.py
diff --git a/lib/stardag/tests/test_registry/test_auth.py b/lib/stardag/tests/test_registry/test_auth.py
