HKUDS/Vibe-Trading · warning · HTTPException

Settings access requires API_AUTH_KEY or a local loopback cl

Error message

Settings access requires API_AUTH_KEY or a local loopback client

What it means

require_local_or_auth protects settings endpoints when dev-mode auth is disabled: with no API_AUTH_KEY configured, settings may only be read from a loopback client; anything else gets 403. When a key IS configured it defers to require_auth instead, so this branch only fires in key-less mode.

Source

Thrown at agent/src/api/security.py:634

    if _is_local_client(request):
        return
    raise HTTPException(
        status_code=status.HTTP_403_FORBIDDEN,
        detail="API_AUTH_KEY is required for non-local API access",
    )


async def require_local_or_auth(
    request: Request,
    cred: Optional[HTTPAuthorizationCredentials] = Security(_security),
) -> None:
    """Protect settings access when dev-mode auth is disabled."""
    if _configured_api_key():
        await require_auth(request, cred)
        return
    if not _is_local_client(request):
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Settings access requires API_AUTH_KEY or a local loopback client",
        )


async def require_settings_write_auth(
    request: Request,
    cred: Optional[HTTPAuthorizationCredentials] = Security(_security),
) -> None:
    """Require explicit authorization before changing credential-routing settings."""
    api_key = _configured_api_key()
    if api_key:
        token = _auth_credential_from_header_or_query(cred, None, allow_query=False)
        if not token or not hmac.compare_digest(token, api_key):
            raise HTTPException(status_code=401, detail="Invalid or missing API key")
        return

    if not _is_local_client(request):

View on GitHub (pinned to 80ffdda44c)

Solutions

1. Read settings from localhost (127.0.0.1) when running key-less
2. Configure API_AUTH_KEY if settings must be accessed remotely, then send the key
3. Restrict network exposure of the API port (firewall/bind to 127.0.0.1) in dev
4. If behind a proxy, make sure forwarded client IP handling is configured before relying on loopback detection

Example fix

# before (no API_AUTH_KEY set)
curl http://server.lan:8000/settings   # 403

# after
curl http://127.0.0.1:8000/settings
# or: set API_AUTH_KEY, then curl -H "Authorization: Bearer $API_AUTH_KEY" http://server.lan:8000/settings

import os
if not os.environ.get("API_AUTH_KEY"):
    assert urlparse(BASE).hostname in ("127.0.0.1", "localhost", "::1"), \
        "Settings reads from a remote host will 403 while no API_AUTH_KEY is set"

try:
    r = client.get("/settings"); r.raise_for_status()
except httpx.HTTPStatusError as e:
    if e.response.status_code == 403:
        # key-less mode: only loopback may read settings
        raise RuntimeError("Run locally or configure API_AUTH_KEY to read settings") from e
    raise

When it happens

Trigger: A GET on a settings route from a non-local address while API_AUTH_KEY is unset and dev-mode auth is disabled.

Common situations: Remote management UI or curl hitting /settings on a key-less dev instance; container orchestration probing the settings endpoint over the pod network; accessing via hostname that resolves to a non-loopback IP.

Related errors

• Settings writes require API_AUTH_KEY or a local loopback cli
• API_AUTH_KEY is required for non-local API access
• Invalid or missing API key
• Feishu / Lark registration does not support client_secret au
• Feishu / Lark registration did not return a device_code

AI-assisted analysis of HKUDS/Vibe-Trading@80ffdda44c (2026-08-28). Data as JSON: /api/errors/414482bf7574ec15. Report an issue: GitHub.