# Connect Azure OpenAI Through APIM

Source: https://userguide.qualytics.io/agentq/how-tos/integration/connect-azure-openai-through-apim/

If you front your Azure OpenAI endpoint with **Azure API Management (APIM)**, point the **Azure OpenAI** provider at the APIM gateway instead of the Azure OpenAI endpoint directly. APIM acts as an OpenAI-compatible proxy. Two settings have to line up, one in APIM and one in Qualytics.

## Prerequisites

- A Qualytics account with the **Manager** or **Admin** role.
- An APIM instance in front of your Azure OpenAI resource, with the Azure OpenAI API imported and its **URL suffix** set to `openai` so the gateway path mirrors a native Azure OpenAI endpoint. This is an APIM setting and is not entered in Qualytics.
- Permission to change the subscription header name in APIM.
- The APIM gateway host and an APIM subscription key.

## Steps

**Step 1**: In APIM, go to **API** > **Settings** > **Subscription** > **Header name** and change it from `Ocp-Apim-Subscription-Key` to `api-key`. The Azure OpenAI client sends its credential in the `api-key` HTTP header, so this one change lets the subscription key travel in the header the client already uses.

**Step 2**: In Qualytics, open the AgentQ setup page and select **Custom setup**. See [Add Integration](https://userguide.qualytics.io/agentq/how-tos/integration/add-integration/).

**Step 3**: Select **Azure OpenAI** as the **Provider**.

**Step 4**: Enter the APIM gateway host as the **Base URL**, using only the host and **no** trailing `/openai`.

```text
https://<your-apim-name>.azure-api.net
```

The Azure OpenAI client appends `/openai/deployments/{deployment}/...?api-version=...` on its own, so adding `/openai` yourself doubles the path and the requests fail.

**Step 5**: Enter the APIM subscription key as the **API Key**.

**Step 6**: Fill in the remaining Azure OpenAI fields and finish connecting, as described in [Add Integration](https://userguide.qualytics.io/agentq/how-tos/integration/add-integration/).

> **Note**
>
> Confirm that the **deployment name** and **api-version** match what is deployed behind APIM. The standard Azure OpenAI import passes both through. If your users attach documents in chat, the api-version has to be **2025-03-01-preview** or later, and the API imported in APIM has to expose the Responses operation (`/openai/responses`), because documents are sent through it rather than through the deployment's chat completions path. APIM authenticates to the real Azure OpenAI backend on its own 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), [importing an Azure OpenAI API](https://learn.microsoft.com/en-us/azure/api-management/azure-openai-api-from-specification), and [subscriptions and custom header names](https://learn.microsoft.com/en-us/azure/api-management/api-management-subscriptions).

*Last updated: November 13, 2026.*
