Version: 1.0.0

Azure OpenAI

Azure OpenAI Service provides Azure-hosted deployments of OpenAI models behind resource-specific endpoints. AISIX lets applications reach those deployments through a single OpenAI-compatible gateway endpoint.

This configuration is for Azure OpenAI deployments that should use AISIX authentication, model allowlists, rate limits, and usage accounting. AISIX can authenticate upstream with a resource API key or an Entra ID client credential.

Prerequisites

Before starting, prepare the following:

One AISIX setup:
- For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
- For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
An Azure OpenAI resource with a deployment.
Either a resource API key or an Entra ID app registration with tenant_id, client_id, and client_secret granted access to the resource.
The Azure OpenAI resource host and deployment name.
curl and jq.

Configure with AISIX Cloud

Export the AISIX Cloud connection details:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash
# The local On-Premises quickstart uses http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Create the provider key with the Azure catalog provider. The control plane derives the azure-openai adapter, so do not send adapter:

# Replace with your values
export AZURE_OPENAI_API_KEY="YOUR_AZURE_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "azure-prod",
    "provider": "azure",
    "api_key": "'"$AZURE_OPENAI_API_KEY"'",
    "api_base": "https://acme-west.openai.azure.com",
    "allowed_environments": ["'"$ENV_ID"'"]
  }' | jq -r '.provider_key.id')

The dashboard's Azure provider form accepts a resource API key. The AISIX Cloud Admin API also accepts the Entra ID credential JSON described above as the api_key value. The API does not accept that credential under config.

Create the model with the Azure deployment name as model_name:

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gpt-4o-azure",
    "model_name": "gpt4o-prod",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

Create a caller API key that can access the model:

AZURE_CALLER_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "azure-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

Configure with the Open-Source AISIX Gateway

Choose the authentication scheme that matches how your Azure OpenAI resource is managed. Both examples below are complete resources files for a new gateway and use the same model and caller-key configuration. For an existing gateway, add the entries from one example to the matching collections in its current resources file. Create a missing collection once and preserve unrelated resources.

Choose the caller API key that applications will send to AISIX before configuring either authentication scheme:

# Replace with your value
export AZURE_CALLER_KEY="YOUR_CALLER_API_KEY"

In both authentication alternatives, provider labels the upstream, adapter selects Azure OpenAI, and api_base points to the Azure OpenAI resource host. AISIX also accepts the bare resource name, such as acme-west. The model's provider_key must match the selected provider key's display_name, and model_name is the Azure deployment name rather than the underlying model ID.

The caller key's allowed_models value must match the model alias. The gateway reads the plaintext caller key from AZURE_CALLER_KEY and stores only a hash. Provider key secrets follow the credential-handling behavior described in Provider Keys.

Use Resource API Key Authentication

Use this option when your Azure OpenAI resource is managed with a resource API key. Export the key so the loader can interpolate it:

# Replace with your value
export AZURE_OPENAI_API_KEY="YOUR_AZURE_API_KEY"

Use the exported provider key and caller key in the complete resources file:

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: azure-prod
    provider: azure
    adapter: azure-openai
    api_key: ${AZURE_OPENAI_API_KEY}
    api_base: https://acme-west.openai.azure.com

models:
  - display_name: gpt-4o-azure
    provider: azure
    model_name: gpt4o-prod
    provider_key: azure-prod

api_keys:
  - display_name: azure-caller
    key_env: AZURE_CALLER_KEY
    allowed_models: ["gpt-4o-azure"]

The provider key interpolates the Azure OpenAI resource API key from the environment. Never place the literal secret in the file.

Use Entra ID Authentication

Use this option when your Azure OpenAI resource should be accessed through an Entra ID app registration. Export the client credential as a JSON value:

# Replace with your values
export AZURE_ENTRA_CREDENTIAL='{"tenant_id":"YOUR_TENANT_ID","client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'

Use the exported client credential and caller key in the complete resources file:

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: azure-aad-prod
    provider: azure
    adapter: azure-openai
    api_key: ${AZURE_ENTRA_CREDENTIAL}
    api_base: https://acme-west.openai.azure.com

models:
  - display_name: gpt-4o-azure
    provider: azure
    model_name: gpt4o-prod
    provider_key: azure-aad-prod

api_keys:
  - display_name: azure-caller
    key_env: AZURE_CALLER_KEY
    allowed_models: ["gpt-4o-azure"]

The JSON credential must include tenant_id, client_id, and client_secret. The client_secret value is the secret value, not the secret ID. For national or sovereign clouds, add authority_host to the JSON credential. Omit it for public Azure. The value must be a bare HTTP(S) origin, such as https://login.microsoftonline.us.

AISIX builds the outbound chat-completions URL from the provider key's api_base and the model's model_name:

https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=2024-10-21

Validate and Load the Resources

If AISIX is installed locally, validate the complete file before loading it:

aisix validate --resources resources.yaml

After validation, start the gateway with the referenced environment variables in its process environment. Reload an existing gateway only if those variables are already available to the process; otherwise, restart it with the updated environment.

If you use Docker, adapt the validation and startup commands in the Open-Source AISIX Gateway Quickstart. Mount this resources.yaml file and pass every environment variable it references with -e in both commands.

Verify the Provider Connection

Export the AISIX gateway origin:

# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

Send a chat-completions request through the AISIX proxy. The request is identical regardless of which upstream authentication scheme the provider key uses.

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AZURE_CALLER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-azure",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Azure OpenAI."
      }
    ]
  }'

The gateway returns an OpenAI-compatible response with the caller-facing alias:

{
  "id": "cmpl_azure_example",
  "object": "chat.completion",
  "model": "gpt-4o-azure",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello from Azure OpenAI!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 7,
    "completion_tokens": 5,
    "total_tokens": 12
  }
}

For a resource API-key provider key, AISIX sends the Azure api-key header. For an Entra ID provider key, AISIX sends Authorization: Bearer <token>.

Check Azure OpenAI metrics, logs, or quota usage for the test request. If AISIX returns an upstream authentication error, check the resource API key or Entra ID credential. If it returns an upstream route error, check api_base, the deployment name in model_name, and the Azure API version supported by your deployment.

Prepare for Production

AISIX currently sends Azure OpenAI requests with api-version=2024-10-21. Confirm that this API version is supported by your Azure OpenAI deployment and track Azure's API version deprecation schedule.

Azure may attach prompt_filter_results and content_filter_results to successful responses. AISIX accepts these Azure extension fields and returns the standard OpenAI-compatible response to the caller.

For a corporate proxy, private endpoint, or test endpoint, set api_base to the exact host AISIX should call. AISIX appends the Azure deployment path and rejects query strings, fragments, and embedded user information.

Next Steps

You have now connected AISIX to Azure OpenAI and verified the model alias. Continue with these guides:

OpenAI: configure a model through the OpenAI API instead of an Azure deployment.
Model Aliases: configure routing, retry behavior, or cost metadata for the alias.
Provider Compatibility: review supported proxy endpoints and provider-specific boundaries.

Prerequisites​

Configure with AISIX Cloud​

Configure with the Open-Source AISIX Gateway​

Use Resource API Key Authentication​

Use Entra ID Authentication​

Validate and Load the Resources​

Verify the Provider Connection​

Prepare for Production​

Next Steps​