{"record":{"id":"3a152e146879f3f0","repo":"BerriAI/litellm","slug":"api-key-azure-ad-token-is-required-for-azure-fou","errorCode":null,"errorMessage":"api_key (Azure AD token) is required for Azure Foundry Agents. Either pass api_key directly, or set AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET environment variables for Service Principal auth. Manual token: az account get-access-token --resource 'https://ai.azure.com'","messagePattern":"api_key \\(Azure AD token\\) is required for Azure Foundry Agents\\. Either pass api_key directly, or set AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET environment variables for Service Principal auth\\. Manual token: az account get-access-token --resource 'https://ai\\.azure\\.com'","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/llms/azure_ai/agents/transformation.py","lineNumber":350,"sourceCode":"          - AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET (Service Principal)\n\n        See: https://learn.microsoft.com/en-us/azure/ai-foundry/agents/quickstart\n        \"\"\"\n        from litellm.llms.azure.common_utils import get_azure_ad_token\n        from litellm.llms.azure_ai.agents.handler import azure_ai_agents_handler\n        from litellm.types.router import GenericLiteLLMParams\n\n        # If no api_key is provided, try to get Azure AD token\n        if api_key is None:\n            # Try to get Azure AD token using the existing Azure auth mechanisms\n            # This uses the scope for Azure AI (ai.azure.com) instead of cognitive services\n            # Create a GenericLiteLLMParams with the scope override for Azure Foundry Agents\n            azure_auth_params: Final = dict(litellm_params) if litellm_params else {}\n            azure_auth_params[\"azure_scope\"] = \"https://ai.azure.com/.default\"\n            api_key = get_azure_ad_token(GenericLiteLLMParams(**azure_auth_params))\n\n        if api_key is None:\n            raise ValueError(\n                \"api_key (Azure AD token) is required for Azure Foundry Agents. \"\n                \"Either pass api_key directly, or set AZURE_TENANT_ID, AZURE_CLIENT_ID, \"\n                \"and AZURE_CLIENT_SECRET environment variables for Service Principal auth. \"\n                \"Manual token: az account get-access-token --resource 'https://ai.azure.com'\"\n            )\n        if acompletion:\n            if stream:\n                # Native async streaming via SSE - return the async generator directly\n                return azure_ai_agents_handler.acompletion_stream(\n                    model=model,\n                    messages=messages,\n                    api_base=api_base,\n                    api_key=api_key,\n                    logging_obj=logging_obj,\n                    optional_params=optional_params,\n                    litellm_params=litellm_params,\n                    timeout=timeout,\n                    headers=headers,","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/azure_ai/agents/transformation.py#L332-L368","documentation":"Azure Foundry Agents authenticate with an Azure AD token for scope https://ai.azure.com/.default. LiteLLM first uses any passed api_key; otherwise it attempts get_azure_ad_token (service principal from AZURE_TENANT_ID/AZURE_CLIENT_ID/AZURE_CLIENT_SECRET, or DefaultAzureCredential). Only if both yield nothing does it raise this ValueError listing every accepted auth route.","triggerScenarios":"No api_key argument and no service-principal env vars in a non-interactive environment (container, CI) where DefaultAzureCredential also finds nothing (no managed identity, no az login). Common when running locally-configured code in Docker or a fresh VM.","commonSituations":"Works on dev laptop (az CLI login feeds DefaultAzureCredential) but fails in CI/containers; AZURE_CLIENT_SECRET rotated but old value still in env; tenant id mistaken for subscription id; secret env vars stripped by a secrets policy.","solutions":["For quick testing, mint a token manually and pass it: az account get-access-token --resource 'https://ai.azure.com' then api_key=<token>.","For production, set AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET for a service principal granted access to the Foundry project.","If on an Azure VM/App Service, enable a managed identity and grant it the project role so DefaultAzureCredential works.","Verify env vars are visible to the litellm process (print names, never values) — a missing var silently triggers this path."],"exampleFix":"# before\nlitellm.completion(model='azure_ai_agents/agent', messages=m, api_base=base)  # no auth anywhere\n\n# after (service principal)\nimport os\nos.environ['AZURE_TENANT_ID'] = '...'\nos.environ['AZURE_CLIENT_ID'] = '...'\nos.environ['AZURE_CLIENT_SECRET'] = '...'\nlitellm.completion(model='azure_ai_agents/agent', messages=m, api_base=base)\n\n# after (manual token, short-lived)\nimport subprocess\ntok = subprocess.check_output(\n    ['az','account','get-access-token','--resource','https://ai.azure.com','--query','accessToken','-o','tsv']\n).decode().strip()\nlitellm.completion(model='azure_ai_agents/agent', messages=m, api_base=base, api_key=tok)","handlingStrategy":"validation","validationCode":"import os\n\ndef foundry_auth_ok(api_key: str | None) -> bool:\n    if api_key:\n        return True\n    return all(os.getenv(v) for v in ('AZURE_TENANT_ID', 'AZURE_CLIENT_ID', 'AZURE_CLIENT_SECRET'))","typeGuard":null,"tryCatchPattern":"try:\n    litellm.completion(model='azure_ai_agents/agent', api_base=base, api_key=token)\nexcept ValueError as e:\n    if 'api_key (Azure AD token) is required' in str(e):\n        raise ConfigurationError('Configure service principal env vars or pass a token') from e\n    raise","preventionTips":["Provision a service principal for non-interactive environments; never rely on az CLI login in prod.","Cache and refresh tokens (they expire ~1h) when minting them yourself.","Add a startup auth check that calls get_azure_ad_token once so failures surface at boot, not mid-request."],"tags":["azure","agents","auth","azure-ad","configuration"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}