BerriAI/litellm · error · HTTPException

LITELLM_SALT_KEY is not configured; plugin iframe auth unava

Error message

LITELLM_SALT_KEY is not configured; plugin iframe auth unavailable.

What it means

Guard in the plugin auth-token endpoint: issuing the encrypted session claim requires deriving a Fernet key from LITELLM_SALT_KEY via HMAC; with the env var unset there is no key material, so iframe auth is refused (503) rather than silently degraded.

Source

Thrown at litellm/proxy/plugin_routes.py:234

@router.get("/api/plugins/auth-token", tags=["plugins"])
async def plugin_auth_token(
    user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth),
    plugin_name: str = "litellm-platform-plugin",
) -> dict:
    """Issue a short-lived, audience-scoped plugin session claim.

    The claim contains {user_id, user_role, plugin, exp}.  It does NOT
    contain the caller's litellm bearer token — a compromised plugin can
    only learn the caller's identity, not impersonate them against the proxy.

    Encrypted with a key derived from HMAC(LITELLM_SALT_KEY, plugin_name),
    so each plugin holds only its own key and cannot forge claims for others.

    Requires LITELLM_SALT_KEY to be set; returns 503 otherwise.
    """
    if not os.getenv("LITELLM_SALT_KEY"):
        raise HTTPException(
            status_code=503,
            detail="LITELLM_SALT_KEY is not configured; plugin iframe auth unavailable.",
        )
    if plugin_name not in _plugin_registry:
        raise HTTPException(status_code=404, detail=f"Plugin '{plugin_name}' is not registered.")
    user_id: Final = getattr(user_api_key_dict, "user_id", None)
    user_role: Final = getattr(user_api_key_dict, "user_role", None)
    return {"session_claim": issue_plugin_session_claim(plugin_name, user_id, user_role)}


@router.api_route(
    "/plugin-proxy/{plugin_name}/{path:path}",
    methods=["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"],
    tags=["plugins"],
    include_in_schema=False,
)
async def plugin_proxy(
    plugin_name: str,

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Set LITELLM_SALT_KEY in the proxy environment and restart to enable plugin iframe auth.

When it happens

Trigger: Thrown at litellm/proxy/plugin_routes.py:234 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/122a995565c6f72a. Report an issue: GitHub.