openai/openai-python · critical · TypeError

"Could not resolve authentication method. Expected either ap

Error message

"Could not resolve authentication method. Expected either api_key, azure_ad_token or azure_ad_token_provider to be set. Or for one of the `Authorization` or `api-key` headers to be explicitly supplied or omitted"

What it means

The sync Azure client found no usable credential: no API key, no Azure AD token/provider, and no explicit Authorization or api-key header. _validate_headers raises TypeError at that point because the request cannot be authenticated.

Source

Thrown at src/openai/lib/azure.py:471

        return None

    @override
    def _auth_headers(self, security: SecurityOptions) -> dict[str, str]:  # noqa: ARG002
        if self._azure_ad_token is not None:
            return {"Authorization": f"Bearer {self._azure_ad_token}"}

        if self.api_key and self.api_key != API_KEY_SENTINEL:
            return {"api-key": self.api_key}

        return {}

    @override
    def _validate_headers(self, headers: Headers, custom_headers: Headers) -> None:
        if _has_auth_header(headers) or _has_auth_header(custom_headers):
            return

        raise TypeError(
            '"Could not resolve authentication method. Expected either api_key, azure_ad_token or azure_ad_token_provider to be set. Or for one of the `Authorization` or `api-key` headers to be explicitly supplied or omitted"'
        )

    @override
    def _prepare_options(self, options: FinalRequestOptions) -> FinalRequestOptions:
        if self._api_key_provider is not None:
            self._refresh_api_key()

        headers: dict[str, str | Omit] = {**options.headers} if is_given(options.headers) else {}

        options = model_copy(options)
        options.headers = headers

        azure_ad_token = self._get_azure_ad_token()
        if azure_ad_token is not None:
            if not _has_header(headers, "Authorization"):
                headers["Authorization"] = f"Bearer {azure_ad_token}"
        elif self.api_key and self.api_key != API_KEY_SENTINEL:

View on GitHub (pinned to 9917c6e28e)

Solutions

Pass api_key or azure_ad_token_provider (e.g. from azure.identity DefaultAzureCredential)
Set AZURE_OPENAI_API_KEY env var
Or supply an explicit Authorization/api-key header in default_headers if you handle auth at a proxy

Example fix

# before
client = AzureOpenAI(azure_endpoint=..., api_version=...)
# after
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
client = AzureOpenAI(azure_endpoint=..., api_version=..., azure_ad_token_provider=get_bearer_token_provider(DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"))

Defensive patterns

Strategy: try-catch

Validate before calling

has_creds = bool(os.environ.get("AZURE_OPENAI_API_KEY") or azure_ad_token or azure_ad_token_provider or auth_header_in_defaults)
if not has_creds: raise RuntimeError("no Azure credential configured")

Try / catch

try:
    client.chat.completions.create(...)
except TypeError as e:
    if "Could not resolve authentication method" in str(e):
        raise AuthConfigError(str(e)) from e
    raise

Prevention

Set AZURE_OPENAI_API_KEY in deployment env
Prefer azure_ad_token_provider for AAD setups
Add a startup credential smoke test

When it happens

Trigger: Constructing AzureOpenAI with none of api_key/azure_ad_token/azure_ad_token_provider, no AZURE_OPENAI_API_KEY env var, and no default Authorization or api-key header, then making any request.

Common situations: Env vars missing in CI/containers, credential code commented out, or assuming the client auto-discovers Azure credentials (only your explicit provider does that).

Understand the failure class

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

Related errors

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/dc9dc9a7d4150639. Report an issue: GitHub.