iflytek/astron-agent · critical · HTTPException

Workflow internal API authentication is not configured

Error message

Workflow internal API authentication is not configured

What it means

configured_workflow_internal_api_key() reads the shared internal API key for Agent<->Workflow authentication and deliberately fails closed: if the key is unset it returns HTTP 503 instead of serving unauthenticated traffic. It guards service-to-service endpoints while deployment configuration is incomplete.

Solutions

1. Set the internal API key env var (e.g. WORKFLOW_INTERNAL_API_KEY) to the same strong random value on both Agent and Workflow services
2. Add the key to docker-compose/helm secrets so deployments get it automatically
3. Restart the Agent service after setting the variable and confirm it is visible in the process environment
4. Ensure key generation/distribution is part of deployment tooling so it can never be empty

Example fix

// before
docker run ... core/agent   # key never provided
// after
docker run -e WORKFLOW_INTERNAL_API_KEY="$SHARED_KEY" ... core/agent

import os
assert os.getenv("WORKFLOW_INTERNAL_API_KEY"), "WORKFLOW_INTERNAL_API_KEY must be set before starting the service"

def internal_auth_configured() -> bool:
    return bool(os.getenv("WORKFLOW_INTERNAL_API_KEY"))

try:
    call_internal_api(url, key=configured_workflow_internal_api_key())
except HTTPException as e:
    if e.status_code == 503:
        logger.error("internal auth not configured; aborting deployment")
        raise

When it happens

Trigger: Any request hitting a route protected by require_workflow_internal_api_key when the internal-key env/config variable is absent or empty in the Agent service (workflow_internal_auth.py:37).

Common situations: Fresh deployment where WORKFLOW_INTERNAL_API_KEY env var was never set; docker-compose/helm values missing the secret; key removed after a config refactor; local dev without the .env file loaded.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Login successful but JSESSIONID cookie not found
• invalid request url
• Both API key and secret must be provided for ifly…
• AGENT_NODE_EXECUTION_ERROR
• Tenant internal authentication is not configured; request…

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/c620732a029ee5b0. Report an issue: GitHub.

Appendix: source

Thrown at core/agent/infra/workflow_internal_auth.py:37

    auto_error=False,
)


def optional_workflow_internal_api_key() -> str:
    """Return a valid deployment-internal key without accepting published defaults."""
    return credential_from_env_or_file(
        WORKFLOW_INTERNAL_API_KEY_ENV,
        WORKFLOW_INTERNAL_API_KEY_FILE_ENV,
        min_length=WORKFLOW_INTERNAL_API_KEY_MIN_LENGTH,
        placeholders=(WORKFLOW_INTERNAL_API_KEY_PLACEHOLDER,),
    )


def configured_workflow_internal_api_key() -> str:
    """Return the configured key or fail closed while deployment is incomplete."""
    api_key = optional_workflow_internal_api_key()
    if not api_key:
        raise HTTPException(
            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
            detail="Workflow internal API authentication is not configured",
        )
    return api_key


async def require_workflow_internal_api_key(
    supplied_api_key: Annotated[
        str | None, Security(_workflow_internal_api_key_header)
    ],
) -> None:
    """Require the same internal credential shared by Workflow and Agent."""
    expected_api_key = configured_workflow_internal_api_key()
    if not supplied_api_key or not secrets.compare_digest(
        supplied_api_key, expected_api_key
    ):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,

View on GitHub (pinned to 5e758547a8)