Please provide an API key or an Azure Active Directory token

Error message

Please provide an API key or an Azure Active Directory token.

What it means

AzureOpenAIChatGenerator requires credentials: either an API key or an Azure Active Directory token must be supplied. If both api_key and azure_ad_token are None, __init__ raises ValueError.

Source

Thrown at haystack/components/generators/chat/azure.py:213

        """
        # We intentionally do not call super().__init__ here because we only need to instantiate the client to interact
        # with the API.

        # Why is this here?
        # AzureOpenAI init is forcing us to use an init method that takes either base_url or azure_endpoint as not
        # None init parameters. This way we accommodate the use case where env var AZURE_OPENAI_ENDPOINT is set instead
        # of passing it as a parameter.
        azure_endpoint = azure_endpoint or os.environ.get("AZURE_OPENAI_ENDPOINT")
        # `azure_endpoint` accepts either a plain string or a `Secret`. We keep the original value on the instance for
        # serialization and resolve it to a string only to validate that an endpoint was provided.
        resolved_azure_endpoint = (
            azure_endpoint.resolve_value() if isinstance(azure_endpoint, Secret) else azure_endpoint
        )
        if not resolved_azure_endpoint:
            raise ValueError("Please provide an Azure endpoint or set the environment variable AZURE_OPENAI_ENDPOINT.")

        if api_key is None and azure_ad_token is None:
            raise ValueError("Please provide an API key or an Azure Active Directory token.")

        # The check above makes mypy incorrectly infer that api_key is never None,
        # which propagates the incorrect type.
        self.api_key = api_key  # type: ignore
        self.azure_ad_token = azure_ad_token
        self.generation_kwargs = generation_kwargs or {}
        self.streaming_callback = streaming_callback
        self.api_version = api_version
        self.azure_endpoint = azure_endpoint
        self.azure_deployment = azure_deployment
        self.organization = organization
        self.model = azure_deployment or "gpt-4.1-mini"
        self.timeout = timeout
        self.max_retries = max_retries
        self.default_headers = default_headers or {}
        self.azure_ad_token_provider = azure_ad_token_provider
        self.http_client_kwargs = http_client_kwargs
        _check_duplicate_tool_names(flatten_tools_or_toolsets(tools))

View on GitHub (pinned to e318778c9b)

Solutions

Pass api_key=Secret.from_env_var("AZURE_OPENAI_API_KEY") explicitly or set the AZURE_OPENAI_API_KEY environment variable
For AAD/Entra auth, pass azure_ad_token (or set AZURE_OPENAI_AD_TOKEN) obtained via azure.identity DefaultAzureCredential
Confirm secrets are mounted/loaded in the deployment environment (kubectl secret, CI secrets, .env loading)

Example fix

// before
generator = AzureOpenAIChatGenerator(azure_endpoint="https://my.openai.azure.com/")  # no credentials
// after
from haystack.utils import Secret
generator = AzureOpenAIChatGenerator(
    azure_endpoint="https://my.openai.azure.com/",
    api_key=Secret.from_env_var("AZURE_OPENAI_API_KEY"),
)

Defensive patterns

Strategy: validation

Validate before calling

import os
if not os.getenv("AZURE_OPENAI_API_KEY") and not os.getenv("AZURE_OPENAI_AD_TOKEN"):
    raise ValueError("Provide AZURE_OPENAI_API_KEY or AZURE_OPENAI_AD_TOKEN")

Try / catch

try:
    generator = AzureOpenAIChatGenerator(api_key=Secret.from_env_var("AZURE_OPENAI_API_KEY"))
except ValueError as e:
    logger.error("Missing Azure credentials: %s", e)
    raise

Prevention

Always use Secret.from_env_var so resolution errors surface with clear messages
For AAD auth, obtain a token via azure.identity and pass it as azure_ad_token
Verify secrets exist in the deployment environment before pipeline startup (fail-fast check)

When it happens

Trigger: Constructing AzureOpenAIChatGenerator() with no api_key/azure_ad_token and with AZURE_OPENAI_API_KEY and AZURE_OPENAI_AD_TOKEN env vars both unset or resolving to None.

Common situations: Forgetting to deploy the .env/secrets in production or CI; using default Secret resolution but never exporting the env vars; switching to AAD auth but passing neither token nor key.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/c15d931f5629b00c. Report an issue: GitHub.