langflow-ai/langflow · error · HTTPException

API key required for this project. Provide x-api-key header

Error message

API key required for this project. Provide x-api-key header or query parameter.

What it means

401 raised when the project's auth configuration requires an API key (project auth_type 'apikey'/'oauth', or no auth settings on a non-AUTO_LOGIN instance) but the request includes neither the x-api-key header nor the x-api-key query parameter. This is the non-oauth variant of the missing-credential branch — the detail string tells you exactly which credential channel to use.

Source

Thrown at src/backend/base/langflow/api/v1/mcp_projects.py:168

    # composer-to-Langflow hop should be authenticated explicitly once mcp-composer can forward
    # a project-scoped backend credential; until then, direct backend access requires a key.
    requires_api_key = (not auth_settings and not settings_service.auth_settings.AUTO_LOGIN) or (
        project_auth_type in {"apikey", "oauth"}
    )

    if requires_api_key:
        api_key = query_param or header_param
        if not api_key:
            if project_auth_type == "oauth":
                detail = (
                    "This project is configured for OAuth authentication, but the MCP transport endpoint "
                    "currently requires a valid x-api-key header or query parameter for backend access. "
                    "Credential forwarding from MCP Composer is not yet available; use an API key in the "
                    "meantime."
                )
            else:
                detail = "API key required for this project. Provide x-api-key header or query parameter."
            raise HTTPException(
                status_code=401,
                detail=detail,
            )

        # Validate the API key
        api_key_result = await authenticate_api_key(db, api_key)
        if not api_key_result:
            raise HTTPException(status_code=401, detail="Invalid API key")
        set_current_auth_context(AuthCredentialContext.from_api_key_result(api_key_result))
        user = api_key_result.user

        # Verify user has access to the project
        project_access = (
            await db.exec(select(Folder).where(Folder.id == project_id, Folder.user_id == user.id))
        ).first()

        if not project_access:
            raise HTTPException(status_code=404, detail="Project not found")

View on GitHub (pinned to 976ec789d2)

Solutions

  1. Add the API key: curl -H 'x-api-key: lf-...' .../api/v1/mcp/project/{id}/ or append ?x-api-key=lf-....
  2. Generate a key for the project owner under Langflow Settings -> API Keys.
  3. If this is a single-user local setup, LANGFLOW_AUTO_LOGIN=true removes the requirement (dev only).
  4. Check the MCP client config supports custom headers and set x-api-key there.

Example fix

# before
resp = await client.get(f"{base}/api/v1/mcp/project/{pid}/sse")

# after
resp = await client.get(f"{base}/api/v1/mcp/project/{pid}/sse", headers={"x-api-key": api_key})
Defensive patterns

Strategy: validation

Validate before calling

import os

def has_mcp_credential() -> bool:
    return bool(os.environ.get('LANGFLOW_API_KEY'))

Try / catch

except 401 'API key required': add x-api-key header and retry; do not retry unchanged.

Prevention

When it happens

Trigger: MCP transport request to a project requiring API keys with no x-api-key in headers or query; also unauthenticated requests when AUTO_LOGIN is false and the project has no auth_settings.

Common situations: Forgetting the API key in curl scripts or MCP client config; disabling AUTO_LOGIN after running open; clients sending Authorization: Bearer <jwt> to a transport endpoint that only accepts x-api-key.

Related errors

AI-assisted analysis of langflow-ai/langflow@976ec789d2 (2026-08-14). Data as JSON: /api/errors/5b2c0248c0cbbfbb. Report an issue: GitHub.