From dea3f312e863efcf42a22353ee111052fc0042c6 Mon Sep 17 00:00:00 2001 From: Eric Simmerman <325330+ets@users.noreply.github.com> Date: Thu, 18 Jun 2026 19:36:57 +0000 Subject: [PATCH] docs(agent-q): document Azure API Management (APIM) support for Azure OpenAI Generated with [Linear](https://linear.app/qualytics/issue/QUA-2033/document-azure-api-management-apim-support-for-the-azure-openai-llm#agent-session-c62a1719) Co-authored-by: linear-code[bot] <222613912+linear-code[bot]@users.noreply.github.com> --- docs/agent-q/managing/add-integration.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/agent-q/managing/add-integration.md b/docs/agent-q/managing/add-integration.md index 036dc713ec..f9c659bd58 100644 --- a/docs/agent-q/managing/add-integration.md +++ b/docs/agent-q/managing/add-integration.md @@ -122,6 +122,29 @@ The **Business Context** you provide is combined with each user's recent chat se When the active provider supports binary content, the chat input shows an **Attach** icon for sending PDFs, Word, Excel, CSV, JSON, XML, plain text, and Markdown files. The button is shown for **Anthropic**, **Google Gemini**, **Amazon Bedrock** (Claude models), **OpenAI**, **Azure OpenAI**, and **Heroku**. Other providers can still receive document content via the [Paste Large Content](./chat-interface-tips.md#paste-large-content){:target="_blank"} flow. See [Attach a File](./chat-interface-tips.md#attach-a-file){:target="_blank"} for limits and supported formats. +## Using Azure API Management (APIM) with Azure OpenAI + +If you front your Azure OpenAI endpoint with **Azure API Management (APIM)**, you can point the **Azure OpenAI** integration at the APIM gateway instead of the Azure OpenAI endpoint directly. APIM acts as a transparent, OpenAI-compatible proxy, so it works as a near drop-in replacement — provided two configuration details line up. + +**1. Base URL** + +Enter the **APIM Gateway URL host** the same way you would a native Azure OpenAI endpoint — just the host, **without** a trailing `/openai`: + +``` +https://.azure-api.net +``` + +The Azure OpenAI client appends `/openai/deployments/{deployment}/...?api-version=...` on its own, so adding `/openai` yourself doubles the path and causes 404s. On the APIM side, the Azure OpenAI API should be imported with its **URL suffix set to** `openai` so the gateway path mirrors a native Azure OpenAI endpoint (an APIM admin setting, not entered in Qualytics). + +**2. API Key / header name** + +Use the **APIM subscription key** as the **API Key**. The Azure OpenAI client sends its credential in the `api-key` HTTP header, but APIM expects the subscription key in `Ocp-Apim-Subscription-Key` by default. In APIM, go to **API → Settings → Subscription → Header name** and change it from `Ocp-Apim-Subscription-Key` to `api-key`. After that change, the subscription key flows through in the header the client already uses, making it a clean drop-in. + +!!! note + Confirm the **deployment name** and **api-version** match what's deployed behind APIM (the standard Azure OpenAI import passes these through). APIM handles authenticating to the real Azure OpenAI backend on its side, so the backend model credentials are never exposed to Qualytics. + +For more detail, see the Azure API Management documentation on [authenticating and authorizing to LLM APIs](https://learn.microsoft.com/en-us/azure/api-management/api-management-authenticate-authorize-ai-apis){:target="_blank"}, [importing an Azure OpenAI API](https://learn.microsoft.com/en-us/azure/api-management/azure-openai-api-from-specification){:target="_blank"}, and [subscriptions and custom header names](https://learn.microsoft.com/en-us/azure/api-management/api-management-subscriptions){:target="_blank"}. + ## What's Next? Want to connect external AI clients like ChatGPT, Claude Desktop, Cursor, or VS Code directly to the Qualytics MCP server? See [Connecting External AI Clients](./connecting-external-ai-clients.md){:target="_blank"} for step-by-step setup guides.