The support team wants to try Claude, and the batch team wants the same model for nightly summaries. You don't
want either team to hold an Anthropic key, and you don't want to edit their code every time you switch models.
In this lab you add Anthropic as a provider whose key only the gateway knows, publish two Claude models behind
aliases such as support-chat, and then point support-chat at a bigger model while the clients keep sending
the same name.
Before you begin
One-time setupThe Setup guide tasks that this lab uses. Mark each one done once, and the labs stop listing it.
- Choose where to run commandsEvery track except the portal
- Sign in to AzureOn your own machine. Cloud Shell is already signed in.
- Install the
aigatewayextensionThe Azure CLI tracks and the Verify steps - Clone the labs repoThe Bicep + azd and Terraform tracks, the notebooks, and the code samples
You've done the one-time setup that this lab uses.
On the Bicep + azd and Terraform tracks, azd up or terraform apply creates its own gateway, Foundry
model, and key, so you can skip this section, except for the Anthropic key. You need only that key and the one-time
setup above.
- Complete Publish a Foundry model and make your first call. You need the gateway, a runtime API key, and the Foundry alias you created there.
- An API key from the Claude Console that can call two models, for example
claude-haiku-5-5andclaude-sonnet-5-5. To use another provider instead, see the values in Add Anthropic as a custom provider. - Permission to change the gateway, for example Contributor on its resource group.
- Run the scripts and samples from the lab's folder,
~/aigateway/labs/03-multi-provider-aliases.
Set these variables once. Every track and the Verify section reuse them.
# Name your gateway, the provider that you create in this lab, and the two Anthropic models
export RG="<resource-group>"
export GATEWAY="<gateway>"
export PROVIDER="anthropic" # the gateway provider you create in this lab
export FAST_MODEL="claude-haiku-5-5" # two models that your Anthropic key can call
export SMART_MODEL="claude-sonnet-5-5"
echo "📝 Gateway $GATEWAY in $RG, provider $PROVIDER, models $FAST_MODEL and $SMART_MODEL"
# Read the gateway's runtime URL, which apps call
export AI_GATEWAY_URL="https://$(az aigateway show -g "$RG" -n "$GATEWAY" --query properties.frontend.defaultHostname -o tsv)"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"
# Paste the gateway runtime key from lab 02, not the Anthropic key. Don't commit it or write it to a file.
printf "AI Gateway API key: " && read -rs AI_GATEWAY_API_KEY && export AI_GATEWAY_API_KEY && echo
echo "🔑 Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"# Name your gateway, the provider that you create in this lab, and the two Anthropic models
$RG = "<resource-group>"
$GATEWAY = "<gateway>"
$PROVIDER = "anthropic" # the gateway provider you create in this lab
$FAST_MODEL = "claude-haiku-5-5" # two models that your Anthropic key can call
$SMART_MODEL = "claude-sonnet-5-5"
Write-Host "📝 Gateway $GATEWAY in $RG, provider $PROVIDER, models $FAST_MODEL and $SMART_MODEL"
# Read the gateway's runtime URL, which apps call
$env:AI_GATEWAY_URL = "https://$(az aigateway show -g $RG -n $GATEWAY --query properties.frontend.defaultHostname -o tsv)"
Write-Host "🌐 Runtime URL: $env:AI_GATEWAY_URL"
# Paste the gateway runtime key from lab 02, not the Anthropic key. Don't commit it or write it to a file.
$env:AI_GATEWAY_API_KEY = Read-Host "AI Gateway API key" -MaskInput
Write-Host "🔑 Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"How it works
The gateway publishes models in three layers:
| Object | What it holds | Unique within | Example |
|---|---|---|---|
| Model provider | A backend endpoint and the credential the gateway uses to call it | The gateway | anthropic, key sent in x-api-key |
| Backend model | A model that the provider serves, and the interfaces it supports | Its provider | claude-haiku-5-5 |
| Alias | The callable name that clients put in the model field. It points to one or more backend models and can carry its own policies. | The gateway | support-chat |
Clients only ever see the gateway URL, their runtime key, and the alias. The provider key stays in the gateway. In this lab each alias points to one backend model. To split traffic across several backend models by priority and weight, see Route an alias across models by priority and weight.
Each interface has its own route under <gateway-url>/default/models:
| Interface | Route |
|---|---|
| OpenAI Chat Completions | /openai/v1/chat/completions |
| OpenAI Responses | /openai/v1/responses |
| Anthropic Messages | /anthropic/v1/messages |
Every model runs in passthrough mode. The gateway keeps the provider's request and response format and doesn't translate between OpenAI and Anthropic, so call each model on an interface it advertises, and retarget an alias only to a model that supports the same interface.
Add Anthropic as a custom provider
The gateway connects to these providers. Microsoft Foundry and Azure OpenAI can use the gateway's managed identity. AWS Bedrock has its own wizard. Every other provider is a custom provider. For both, the gateway stores the API key.
| Provider | How you add it | Gateway authenticates with | |
|---|---|---|---|
| Microsoft Foundry | Models from Microsoft Foundry | Managed identity (recommended) or API key | |
| Azure OpenAI | Models from Microsoft Foundry | Managed identity (recommended) or API key | |
| OpenAI | Models from a custom provider | API key | |
| Anthropic | Models from a custom provider | API key | |
| AWS Bedrock | Models from AWS Bedrock | Bedrock API key (the gateway adds the Bearer prefix) | |
| Google Vertex AI | Models from a custom provider | API key | |
| Any other OpenAI-compatible endpoint | Models from a custom provider | API key |
Pick one track. Every track creates the same result: a provider named anthropic, two backend models, and two
aliases. support-chat points to the fast model, and anthropic/claude-sonnet-5-5 points to the bigger one. The
Bicep + azd and Terraform tracks also declare the batch-chat alias and the token limits of the next section.
Start the custom provider wizard
Open the AI Gateway portal and select your gateway from the gateway switcher. Select ModelsAddModels from a custom provider. Add custom provider in the Set up your gateway guide on Home opens the same wizard.
On the Provider step, select Create new provider and fill in Basic info:
| Field | Value |
|---|---|
| Display name | Anthropic |
| Provider name | anthropic, which the wizard fills in from the display name. It's used in the resource ID, and you can't change it later. |
| Description | Optional |
Select Next.
Connect the endpoint
On the Endpoint step, fill in Endpoint and authentication:
| Field | Value for Anthropic |
|---|---|
| Base endpoint URL | https://api.anthropic.com |
| Header name | x-api-key, in place of the default Authorization |
| API key | Your Anthropic API key |
| Authentication scheme | Leave Include Bearer scheme in the authorization header value cleared. Anthropic expects the raw key. |
The wizard lists the provider's models by calling <base endpoint URL>/v1/models, so leave /v1 off the base
URL. The key is stored in the gateway. Apps that call the gateway never receive it.
For other providers, change these values:
| Provider | Base endpoint URL | Header name | Authentication scheme |
|---|---|---|---|
| OpenAI | https://api.openai.com | Authorization | Selected, so the gateway sends Bearer <key> |
| Other OpenAI-compatible endpoints | The URL in front of /v1/... | The header the endpoint expects | As the endpoint expects |
| Google Vertex AI | The provider's OpenAI-compatible endpoint, without the /v1/... path | The header that the provider's API key goes in | As the provider expects |
Select Next.
Choose the models and their aliases
The Models step calls the provider to discover its models. Select AddIndividual model, fill in the Add model dialog for each model, and select Add:
| Field | First model | Second model |
|---|---|---|
| Backend model | claude-haiku-5-5 | claude-sonnet-5-5 |
| Create an alias | Selected | Selected |
| Alias | Change the default, anthropic/claude-haiku-5-5, to support-chat | Keep the default, anthropic/claude-sonnet-5-5 |
| API format | Anthropic Messages. Provider path fills in as /v1/messages. | Anthropic Messages |
If the step shows No models discovered., check the base URL and the key. You can still add the models by hand. When Included lists both models, select Add models.
Models lists the two Claude models of the Anthropic provider and the aliases support-chat and
anthropic/claude-sonnet-5-5. Open a model: under Endpoints, its Overview shows the Messages
endpoint, <gateway-url>/default/models/anthropic/v1/messages.
Check the variables
The provider, its models, and the aliases are child resources of the gateway's default workspace. You set
RG, GATEWAY, PROVIDER, FAST_MODEL, and SMART_MODEL in Before you begin. Check that
they point at your gateway by listing its model providers. The command is the same in Bash and PowerShell.
# List the gateway's model providers, to check that the variables point at your gateway
echo "🔌 Model providers on your gateway:"
az aigateway model-provider list -g "$RG" --gateway-name "$GATEWAY" -o tableThe table lists the provider from lab 02, of kind Foundry. If the command fails, set the variables again.
Create the provider
The command reads the Anthropic key from a hidden prompt, so it never lands in your shell history. The command
output, like az aigateway model-provider show, never includes the key.
# Read the Anthropic key from a hidden prompt, so that it never lands in your shell history
printf "Anthropic API key: " && read -rs ANTHROPIC_API_KEY && echo
echo "🔑 Anthropic key: in ANTHROPIC_API_KEY (${#ANTHROPIC_API_KEY} characters, not shown)"
# Add Anthropic as a custom provider: the gateway stores the key and sends it in the x-api-key header
az aigateway model-provider create -g "$RG" --gateway-name "$GATEWAY" -n "$PROVIDER" \
--kind Custom --display-name "Anthropic" \
--custom "$(jq -cn --arg key "$ANTHROPIC_API_KEY" '{
endpoint: "https://api.anthropic.com",
authentication: {kind: "ApiKey", apiKey: {headerName: "x-api-key", value: $key}}}')" \
--query "{name:name,kind:properties.modelProviderType,endpoint:properties.custom.endpoint.url}" &&
echo "🔌 Model provider $PROVIDER is ready, and its key stays in the gateway"
# Clear the key from your shell, now that the gateway stores it
unset ANTHROPIC_API_KEY &&
echo "🚮 ANTHROPIC_API_KEY is cleared from this shell"# Read the Anthropic key from a hidden prompt, so that it never lands in your shell history
$key = Read-Host "Anthropic API key" -MaskInput
Write-Host "🔑 Anthropic key: in the key variable ($($key.Length) characters, not shown)"
# Write the provider settings to a file: the endpoint, and the key that the gateway sends in the x-api-key header
@{
endpoint = 'https://api.anthropic.com'
authentication = @{ kind = 'ApiKey'; apiKey = @{ headerName = 'x-api-key'; value = $key } }
} | ConvertTo-Json -Depth 10 -Compress | Set-Content -Path custom.json
# Add Anthropic as a custom provider: the gateway stores the key, and apps never receive it
az aigateway model-provider create -g $RG --gateway-name $GATEWAY -n $PROVIDER `
--kind Custom --display-name "Anthropic" --custom '@custom.json' `
--query "{name:name,kind:properties.modelProviderType,endpoint:properties.custom.endpoint.url}"
if ($?) { Write-Host "🔌 Model provider $PROVIDER is ready, and its key stays in the gateway" }
# Delete the file and the variable right away, because they held the key
Remove-Item custom.json; Remove-Variable key
if ($?) { Write-Host "🚮 custom.json and the key variable are deleted" }For OpenAI, use https://api.openai.com, the header Authorization, and the value Bearer <key>.
Register the backend models
A backend model names one of the provider's models. Its name (--name) may only contain lowercase letters, digits,
and hyphens. If the provider's model ID contains other characters, replace them with - in --name and keep the
real ID in modelName.
# Register both Claude models as backend models of the provider, on the Anthropic Messages path, /v1/messages
for MODEL in "$FAST_MODEL" "$SMART_MODEL"; do
az aigateway model create -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" \
--display-name "$MODEL" --supported-endpoints /v1/messages --deployment-config "{modelName:$MODEL}" \
--query "{name:name,endpoints:properties.supportedEndpoints}" -o json &&
echo "✨ Backend model $MODEL is published through $PROVIDER"
done# Register both Claude models as backend models of the provider, on the Anthropic Messages path, /v1/messages
foreach ($model in $FAST_MODEL, $SMART_MODEL) {
az aigateway model create -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER -n $model `
--display-name $model --supported-endpoints /v1/messages --deployment-config "{modelName:$model}" `
--query "{name:name,endpoints:properties.supportedEndpoints}" -o json
if ($?) { Write-Host "✨ Backend model $model is published through $PROVIDER" }
}The provider settings and model bodies mirror what the portal sends. For custom providers, supportedEndpoints
holds the provider path: /v1/messages for Anthropic, /v1/chat/completions or /v1/responses for
OpenAI-compatible endpoints. Leave out --api-format for custom providers. If the service rejects either
command, create the provider and models with the Portal tab, then continue here with the aliases.
The CLI stores the provider in the shape of the GA management API (2026-11-01): modelProviderType: "Custom",
the URL in custom.endpoint.url, and the key in authentication.headers, a list with exactly one
{name, value} header. That's why the command's output shows "kind": "Custom" and the URL. A GET, like
az aigateway model-provider show, returns the header name but never its value, so a full PUT to the provider
must send the key again.
Create the aliases
An alias lists its backend models by resource ID in properties.backendModels. Here each alias has one. The
callable name goes in properties.aliasName, which --routing-name sets, and -n sets the resource name.
Callable names may contain /, but resource names can't, so the script derives the resource name the same way
the portal does: anthropic/claude-sonnet-5-5 is stored as anthropic-claude-sonnet-5-5.
# Create the support-chat alias on the fast model
./infra/alias.sh put support-chat "$PROVIDER" "$FAST_MODEL" &&
echo "🔖 Alias support-chat is ready"
# Create an alias for the bigger model, named after the provider and the model, as the portal does
./infra/alias.sh put "$PROVIDER/$SMART_MODEL" "$PROVIDER" "$SMART_MODEL" &&
echo "🔖 Alias $PROVIDER/$SMART_MODEL is ready"# Create the support-chat alias on the fast model
./infra/alias.ps1 -ResourceGroup $RG -Gateway $GATEWAY put support-chat $PROVIDER $FAST_MODEL
if ($?) { Write-Host "🔖 Alias support-chat is ready" }
# Create an alias for the bigger model, named after the provider and the model, as the portal does
./infra/alias.ps1 -ResourceGroup $RG -Gateway $GATEWAY put "$PROVIDER/$SMART_MODEL" $PROVIDER $SMART_MODEL
if ($?) { Write-Host "🔖 Alias $PROVIDER/$SMART_MODEL is ready" }On GitHub, open alias.sh or alias.ps1. Each put runs a command like this.
az aigateway model-alias set creates the alias, or updates it if it already exists.
az aigateway model-alias set -g <resource-group> --gateway-name <gateway> -n support-chat \
--routing-name support-chat \
--backend-model resource-id=.../workspaces/default/modelProviders/anthropic/models/claude-haiku-5-5 \
--policies '[]' --only-show-errors -o none./infra/alias.sh list shows support-chat → anthropic/claude-haiku-5-5 and
anthropic/claude-sonnet-5-5 → anthropic/claude-sonnet-5-5, next to your Foundry alias from lab 02.
What you need: only the one-time setup from Before you begin. This track doesn't use your gateway from earlier
labs: azd up creates a new one, so it works on its own.
Choose what to declare
The provider, its models, and the aliases are child resources of the gateway's default workspace:
modelProviders, modelProviders/models, and aliases. The template declares the same bodies as the Azure CLI
track. The Anthropic key is a @secure() parameter: the gateway stores it, and it never shows in the deployment
history, the outputs, or the az aigateway model-provider show output.
| azd environment value | Parameter | Default |
|---|---|---|
ANTHROPIC_API_KEY | anthropicApiKey | None. azd up asks for it if you don't set it. |
FAST_MODEL | fastModel | claude-haiku-5-5 |
SMART_MODEL | smartModel | claude-sonnet-5-5 |
SUPPORT_CHAT_MODEL | supportChatModel | The fast model |
SUPPORT_CHAT_TOKENS_PER_MINUTE | supportChatTokensPerMinute | 20000 |
BATCH_CHAT_TOKENS_PER_MINUTE | batchChatTokensPerMinute | 2000 |
Review the templates
infra/main.bicep creates the resource group rg-<environment name> and calls the quick start's
resources.bicep for the gateway, the Foundry model, its default alias, and the
runtime key. Then it calls infra/anthropic-aliases.bicep with the Anthropic key and the model names:
// Lab 03 with azd: "azd up" creates the resource group rg-<environment name>, the quick start's gateway, Foundry
// model, default alias, and runtime API key, then an Anthropic provider with two Claude models behind three
// aliases. The Anthropic key comes from ANTHROPIC_API_KEY in the azd environment and is never an output.
targetScope = 'subscription'
@description('azd environment name. The resource group is rg-<environmentName>.')
@minLength(1)
@maxLength(60)
param environmentName string
@description('Region for every resource. Pick one where AI Gateway and the lab\'s Foundry models are available. List them with az provider show --namespace Microsoft.ApiManagement (Setup guide, Find the available regions).')
@metadata({ azd: { type: 'location' } })
param location string
@secure()
@description('The Anthropic API key. azd reads it from ANTHROPIC_API_KEY.')
param anthropicApiKey string
@description('A fast model that your Anthropic key can call. azd reads it from FAST_MODEL.')
param fastModel string = 'claude-haiku-5-5'
@description('A bigger model that your Anthropic key can call. azd reads it from SMART_MODEL.')
param smartModel string = 'claude-sonnet-5-5'
@description('The backend model behind support-chat: empty for fastModel, or smartModel. azd reads it from SUPPORT_CHAT_MODEL.')
param supportChatModel string = ''
@description('Per-caller tokens per minute for support-chat. azd reads it from SUPPORT_CHAT_TOKENS_PER_MINUTE.')
@minValue(1)
param supportChatTokensPerMinute int = 20000
@description('Per-caller tokens per minute for batch-chat. azd reads it from BATCH_CHAT_TOKENS_PER_MINUTE.')
@minValue(1)
param batchChatTokensPerMinute int = 2000
var suffix = take(uniqueString(subscription().id, environmentName, location), 6)
var tags = { 'azd-env-name': environmentName }
resource rg 'Microsoft.Resources/resourceGroups@2024-03-01' = {
name: 'rg-${environmentName}'
location: location
tags: tags
}
// The quick start's template: a gateway, a Foundry model behind the default alias, and the app-first-call key.
module base '../../quickstart/infra/resources.bicep' = {
name: 'aigw-base'
scope: rg
params: {
location: location
tags: tags
gatewayName: 'aigw-${suffix}'
foundryName: 'aigw${suffix}'
}
}
module anthropic 'anthropic-aliases.bicep' = {
name: 'aigw-anthropic-aliases'
scope: rg
params: {
gatewayName: base.outputs.gatewayName
anthropicApiKey: anthropicApiKey
fastModel: fastModel
smartModel: smartModel
supportChatModel: empty(supportChatModel) ? fastModel : supportChatModel
supportChatTokensPerMinute: supportChatTokensPerMinute
batchChatTokensPerMinute: batchChatTokensPerMinute
}
}
output AZURE_RESOURCE_GROUP string = rg.name
output AI_GATEWAY_NAME string = base.outputs.gatewayName
output AI_GATEWAY_ID string = base.outputs.gatewayId
output AI_GATEWAY_URL string = base.outputs.gatewayUrl
output AI_GATEWAY_PROVIDER string = base.outputs.providerName
output AI_GATEWAY_BACKEND_MODEL string = base.outputs.modelName
output AI_GATEWAY_MODEL string = base.outputs.aliasName
output FOUNDRY_ACCOUNT_NAME string = base.outputs.foundryName
output ANTHROPIC_PROVIDER string = anthropic.outputs.providerName
output ANTHROPIC_FAST_MODEL string = anthropic.outputs.fastModel
output ANTHROPIC_SMART_MODEL string = anthropic.outputs.smartModelinfra/anthropic-aliases.bicep declares the provider, the two backend models, and the three aliases, each with its
callable name in aliasName and its token limit in policies. The provider's key goes in authentication.headers,
and every deployment sends it again, because the gateway never returns it. The template only references the gateway,
so you can also deploy it on its own to a gateway you already have, with az deployment group create:
// Adds Anthropic to an existing AI Gateway as a custom provider, registers two Claude models, and publishes them
// behind three callable aliases: support-chat and batch-chat, each with its own per-caller token limit, and
// anthropic/<smart model>. main.bicep calls it after the quick start's template, and you can also deploy it on its
// own to a gateway you already have. The Anthropic key is a secure parameter: the gateway stores it, it never
// appears in the deployment history or the outputs, and clients never receive it.
@description('Name of the existing AI Gateway (Microsoft.ApiManagement/aigateways).')
param gatewayName string
@description('Name of the custom provider to create. It\'s part of the resource ID, so you can\'t change it later.')
param providerName string = 'anthropic'
@secure()
@description('The Anthropic API key that the gateway sends to Anthropic in the x-api-key header.')
param anthropicApiKey string
@description('A fast model that your Anthropic key can call.')
param fastModel string = 'claude-haiku-5-5'
@description('A bigger model that your Anthropic key can call.')
param smartModel string = 'claude-sonnet-5-5'
@description('The backend model behind the support-chat alias: fastModel or smartModel.')
param supportChatModel string = fastModel
@description('Per-caller tokens per minute for the support-chat alias.')
@minValue(1)
param supportChatTokensPerMinute int = 20000
@description('Per-caller tokens per minute for the batch-chat alias.')
@minValue(1)
param batchChatTokensPerMinute int = 2000
#disable-next-line BCP081
resource gateway 'Microsoft.ApiManagement/aigateways@2026-11-01' existing = {
name: gatewayName
}
#disable-next-line BCP081
resource workspace 'Microsoft.ApiManagement/aigateways/workspaces@2026-11-01' existing = {
parent: gateway
name: 'default'
}
// Leave /v1 off the endpoint. Anthropic expects the raw key in x-api-key, with no "Bearer" scheme. A custom provider
// takes exactly one header, and reads hide its value, so every deployment sends the key again.
#disable-next-line BCP081
resource provider 'Microsoft.ApiManagement/aigateways/workspaces/modelProviders@2026-11-01' = {
parent: workspace
name: providerName
properties: {
modelProviderType: 'Custom'
displayName: 'Anthropic'
description: 'Anthropic Messages API, with the key in the x-api-key header.'
custom: {
endpoint: {
url: 'https://api.anthropic.com'
}
}
authentication: {
headers: [
{
name: 'x-api-key'
value: anthropicApiKey
}
]
}
}
}
// Custom providers list the provider path in supportedEndpoints and leave out apiFormat. Names may only contain
// lowercase letters, digits, and hyphens; modelName keeps the provider's real model ID.
#disable-next-line BCP081
resource models 'Microsoft.ApiManagement/aigateways/workspaces/modelProviders/models@2026-11-01' = [for name in [ fastModel, smartModel ]: {
parent: provider
name: name
properties: {
displayName: name
supportedEndpoints: [ '/v1/messages' ]
deployment: {
modelName: name
}
}
}]
var fastModelId = models[0].id
var smartModelId = models[1].id
// The callable name goes in aliasName and can contain "/". The resource name can't, so it uses "-" instead.
var aliases = [
{
name: 'support-chat'
aliasName: 'support-chat'
modelId: supportChatModel == smartModel ? smartModelId : fastModelId
tokensPerMinute: supportChatTokensPerMinute
}
{
name: 'batch-chat'
aliasName: 'batch-chat'
modelId: fastModelId
tokensPerMinute: batchChatTokensPerMinute
}
{
name: '${providerName}-${smartModel}'
aliasName: '${providerName}/${smartModel}'
modelId: smartModelId
tokensPerMinute: 0
}
]
#disable-next-line BCP081
resource aliasResources 'Microsoft.ApiManagement/aigateways/workspaces/aliases@2026-11-01' = [for alias in aliases: {
parent: workspace
name: alias.name
properties: {
aliasName: alias.aliasName
backendModels: [
{ resourceId: alias.modelId }
]
policies: alias.tokensPerMinute > 0 ? [
{
type: 'tokenLimit'
count: alias.tokensPerMinute
period: 'minute'
counterKey: [ 'identity' ]
}
] : []
}
}]
output providerName string = provider.name
output fastModel string = models[0].name
output smartModel string = models[1].name
output aliasNames array = [for (alias, i) in aliases: aliasResources[i].properties.aliasName]
output messagesUrl string = 'https://${gateway.properties.frontend.defaultHostname}/default/models/anthropic/v1/messages'Deploy with azd up
Move into the lab's folder, create an azd environment named aigw-lab03 in your current subscription, and give it the
Anthropic key from a hidden prompt, so that it never lands in your shell history. Then provision everything. It takes
about two minutes.
# Move into the lab's folder, which holds the azd project
cd ~/aigateway/labs/03-multi-provider-aliases &&
echo "📂 Lab folder: $(pwd)"
# Create an azd environment in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab03 --location eastus2 --subscription "$(az account show --query id --output tsv)" &&
echo "📝 azd environment aigw-lab03 deploys to eastus2"
# Read the Anthropic key from a hidden prompt, so that it never lands in your shell history
printf "Anthropic API key: " && read -rs ANTHROPIC_API_KEY && echo
echo "🔑 Anthropic key: in ANTHROPIC_API_KEY (${#ANTHROPIC_API_KEY} characters, not shown)"
# Store the key in the azd environment, which passes it to the template's secure parameter
azd env set ANTHROPIC_API_KEY "$ANTHROPIC_API_KEY" &&
echo "📝 ANTHROPIC_API_KEY is set in the azd environment"
# Clear the key from your shell, now that the azd environment holds it
unset ANTHROPIC_API_KEY &&
echo "🚮 ANTHROPIC_API_KEY is cleared from this shell"
# Provision the gateway, the Foundry model, the key, the Anthropic provider, its models, and the aliases
azd up &&
echo "🚀 Gateway deployed: $(azd env get-value AI_GATEWAY_URL)"# Move into the lab's folder, which holds the azd project
Set-Location ~/aigateway/labs/03-multi-provider-aliases
if ($?) { Write-Host "📂 Lab folder: $(Get-Location)" }
# Create an azd environment in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab03 --location eastus2 --subscription (az account show --query id --output tsv)
if ($?) { Write-Host "📝 azd environment aigw-lab03 deploys to eastus2" }
# Read the Anthropic key from a hidden prompt, so that it never lands in your shell history
$key = Read-Host "Anthropic API key" -MaskInput
Write-Host "🔑 Anthropic key: in the key variable ($($key.Length) characters, not shown)"
# Store the key in the azd environment, which passes it to the template's secure parameter
azd env set ANTHROPIC_API_KEY $key
if ($?) { Write-Host "📝 ANTHROPIC_API_KEY is set in the azd environment" }
# Clear the key from your shell, now that the azd environment holds it
Remove-Variable key
if ($?) { Write-Host "🚮 The key variable is cleared from this shell" }
# Provision the gateway, the Foundry model, the key, the Anthropic provider, its models, and the aliases
azd up
if ($?) { Write-Host "🚀 Gateway deployed: $(azd env get-value AI_GATEWAY_URL)" }For another region, pick one where AI Gateway and the gpt-5-mini model are available, as in Find the available
regions. azd keeps the key in .azure/aigw-lab03/.env,
which .azure/.gitignore keeps out of Git. If your Claude Console key can't call the default models, set FAST_MODEL
and SMART_MODEL with azd env set before azd up.
Read the outputs and the key
Set the variables that the next sections and Verify use from azd's environment values, and read the gateway's runtime key, not the Anthropic key, from the gateway, so that it never shows on screen.
# Read the template's outputs: the gateway, the provider, the two models, and the runtime URL
export RG="$(azd env get-value AZURE_RESOURCE_GROUP)"
export GATEWAY="$(azd env get-value AI_GATEWAY_NAME)"
export PROVIDER="$(azd env get-value ANTHROPIC_PROVIDER)"
export FAST_MODEL="$(azd env get-value ANTHROPIC_FAST_MODEL)"
export SMART_MODEL="$(azd env get-value ANTHROPIC_SMART_MODEL)"
export AI_GATEWAY_URL="$(azd env get-value AI_GATEWAY_URL)"
echo "📝 Gateway $GATEWAY in $RG, provider $PROVIDER, models $FAST_MODEL and $SMART_MODEL"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"
# Read the gateway's runtime key from the gateway, so that it never lands in a file or a deployment log
export AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets \
--ids "$(azd env get-value AI_GATEWAY_ID)/apiKeys/app-first-call" --query primaryKey --output tsv)"
echo "🔑 Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"
# List the aliases that azd up created, with their backend models and token limits
echo "🔖 Aliases on $GATEWAY:"
./infra/alias.sh list# Read the template's outputs: the gateway, the provider, the two models, and the runtime URL
$RG = azd env get-value AZURE_RESOURCE_GROUP
$GATEWAY = azd env get-value AI_GATEWAY_NAME
$PROVIDER = azd env get-value ANTHROPIC_PROVIDER
$FAST_MODEL = azd env get-value ANTHROPIC_FAST_MODEL
$SMART_MODEL = azd env get-value ANTHROPIC_SMART_MODEL
$env:AI_GATEWAY_URL = azd env get-value AI_GATEWAY_URL
Write-Host "📝 Gateway $GATEWAY in $RG, provider $PROVIDER, models $FAST_MODEL and $SMART_MODEL"
Write-Host "🌐 Runtime URL: $env:AI_GATEWAY_URL"
# Read the gateway's runtime key from the gateway, so that it never lands in a file or a deployment log
$env:AI_GATEWAY_API_KEY = az aigateway api-key list-secrets `
--ids "$(azd env get-value AI_GATEWAY_ID)/apiKeys/app-first-call" --query primaryKey --output tsv
Write-Host "🔑 Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"
# List the aliases that azd up created, with their backend models and token limits
Write-Host "🔖 Aliases on ${GATEWAY}:"
./infra/alias.ps1 -ResourceGroup $RG -Gateway $GATEWAY listazd up ended with SUCCESS. The list shows support-chat → anthropic/claude-haiku-5-5, batch-chat →
anthropic/claude-haiku-5-5, and anthropic/claude-sonnet-5-5 → anthropic/claude-sonnet-5-5, next to the
quick start's gpt-5-mini → foundry-models/gpt-5-mini.
What you need: the one-time setup and the Anthropic key from Before you begin, plus Terraform 1.11 or later,
as in Deploy a lab with Terraform. The configuration keeps the Anthropic
key in a write-only argument, which needs Terraform 1.11. This track doesn't use your gateway from earlier labs:
terraform apply creates a new one, so it works on its own.
Review the configuration
The configuration declares the same objects as the Bicep template. The Anthropic key is an ephemeral, sensitive
variable: Terraform passes it to the azapi provider's write-only sensitive_body, so it never shows in the state,
the saved plan, the outputs, or the az aigateway model-provider show output.
| Terraform variable | Default |
|---|---|
anthropic_api_key | None. The next step sets TF_VAR_anthropic_api_key from a hidden prompt. |
fast_model | claude-haiku-5-5 |
smart_model | claude-sonnet-5-5 |
support_chat_model | Empty, for the fast model |
support_chat_tokens_per_minute | 20000 |
batch_chat_tokens_per_minute | 2000 |
terraform/main.tf creates the resource group rg-<environment_name> and calls the quick start's
resources module for the gateway, the Foundry model, its default alias, and the
app-first-call key:
# Lab 03 with Terraform: creates the resource group rg-<environment_name>, the quick start's gateway, Foundry model,
# default alias, and runtime API key, then an Anthropic provider with two Claude models behind three aliases
# (anthropic-aliases.tf). The Anthropic key comes from TF_VAR_anthropic_api_key and is never an output.
data "azapi_client_config" "current" {}
locals {
suffix = substr(sha1("${data.azapi_client_config.current.subscription_id}/${var.environment_name}/${var.location}"), 0, 6)
tags = { "environment-name" = var.environment_name }
}
resource "azurerm_resource_group" "rg" {
name = "rg-${var.environment_name}"
location = var.location
tags = local.tags
}
# The quick start's module: a gateway, a Foundry model behind the default alias, and the app-first-call key.
module "base" {
source = "../../quickstart/terraform/resources"
subscription_id = data.azapi_client_config.current.subscription_id
resource_group_name = azurerm_resource_group.rg.name
resource_group_id = azurerm_resource_group.rg.id
location = var.location
tags = local.tags
gateway_name = "aigw-${local.suffix}"
foundry_name = "aigw${local.suffix}"
}terraform/anthropic-aliases.tf adds the provider, its two models, and the three aliases with the azapi provider,
which sends the AI Gateway API version, 2026-11-01, as is. terraform/variables.tf declares the variables of the
table:
# Adds Anthropic to the gateway as a custom provider, registers two Claude models, and publishes them behind three
# callable aliases: support-chat and batch-chat, each with its own per-caller token limit, and anthropic/<smart model>.
# Write-only arguments, such as sensitive_body, need Terraform 1.11 or later.
terraform {
required_version = ">= 1.11"
}
locals {
provider_name = "anthropic"
support_chat_model = var.support_chat_model == "" ? var.fast_model : var.support_chat_model
# The callable name goes in aliasName and can contain "/". The resource name can't, so it uses "-" instead.
aliases = {
"support-chat" = {
alias_name = "support-chat"
model = local.support_chat_model
tokens_per_minute = var.support_chat_tokens_per_minute
}
"batch-chat" = {
alias_name = "batch-chat"
model = var.fast_model
tokens_per_minute = var.batch_chat_tokens_per_minute
}
"${local.provider_name}-${var.smart_model}" = {
alias_name = "${local.provider_name}/${var.smart_model}"
model = var.smart_model
tokens_per_minute = 0
}
}
}
# Leave /v1 off the endpoint. Anthropic expects the raw key in x-api-key, with no "Bearer" scheme. The header goes in
# sensitive_body, which is write-only: Terraform sends it on every create and update, because reads hide its value,
# and never stores it in the state.
resource "azapi_resource" "anthropic" {
type = "Microsoft.ApiManagement/aigateways/workspaces/modelProviders@2026-11-01"
name = local.provider_name
parent_id = module.base.workspace_id
body = {
properties = {
modelProviderType = "Custom"
displayName = "Anthropic"
description = "Anthropic Messages API, with the key in the x-api-key header."
custom = {
endpoint = {
url = "https://api.anthropic.com"
}
}
}
}
sensitive_body = {
properties = {
authentication = {
headers = [
{
name = "x-api-key"
value = var.anthropic_api_key
}
]
}
}
}
schema_validation_enabled = false
}
# Custom providers list the provider path in supportedEndpoints and leave out apiFormat. Names may only contain
# lowercase letters, digits, and hyphens; modelName keeps the provider's real model ID.
resource "azapi_resource" "anthropic_model" {
for_each = toset([var.fast_model, var.smart_model])
type = "Microsoft.ApiManagement/aigateways/workspaces/modelProviders/models@2026-11-01"
name = each.key
parent_id = azapi_resource.anthropic.id
body = {
properties = {
displayName = each.key
supportedEndpoints = ["/v1/messages"]
deployment = {
modelName = each.key
}
}
}
schema_validation_enabled = false
}
resource "azapi_resource" "anthropic_alias" {
for_each = local.aliases
type = "Microsoft.ApiManagement/aigateways/workspaces/aliases@2026-11-01"
name = each.key
parent_id = module.base.workspace_id
body = {
properties = {
aliasName = each.value.alias_name
backendModels = [
{ resourceId = azapi_resource.anthropic_model[each.value.model].id }
]
policies = [
for count in(each.value.tokens_per_minute > 0 ? [each.value.tokens_per_minute] : []) : {
type = "tokenLimit"
count = count
period = "minute"
counterKey = ["identity"]
}
]
}
}
schema_validation_enabled = false
}Deploy with terraform apply
Move into the lab's Terraform folder, select your current subscription, and give Terraform the Anthropic key from a hidden prompt, so that it never lands in your shell history. Then plan and apply the configuration. It takes two to ten minutes, most of it while the new gateway activates.
# Move into the lab's Terraform folder
cd ~/aigateway/labs/03-multi-provider-aliases/terraform &&
echo "📂 Terraform folder: $(pwd)"
# Deploy to the Azure CLI's current subscription
export ARM_SUBSCRIPTION_ID="$(az account show --query id --output tsv)" &&
echo "📍 Subscription: $ARM_SUBSCRIPTION_ID"
# Read the Anthropic key from a hidden prompt into the variable that Terraform reads
printf "Anthropic API key: " && read -rs TF_VAR_anthropic_api_key && export TF_VAR_anthropic_api_key && echo
echo "🔑 Anthropic key: in TF_VAR_anthropic_api_key (${#TF_VAR_anthropic_api_key} characters, not shown)"
# Download the providers, then plan and apply the gateway, the Foundry model, the key, the Anthropic provider, its
# models, and the aliases
terraform init &&
terraform plan -out tfplan &&
terraform apply tfplan &&
echo "🚀 Gateway deployed: $(terraform output -raw ai_gateway_url)"# Move into the lab's Terraform folder
Set-Location ~/aigateway/labs/03-multi-provider-aliases/terraform
if ($?) { Write-Host "📂 Terraform folder: $(Get-Location)" }
# Deploy to the Azure CLI's current subscription
$env:ARM_SUBSCRIPTION_ID = az account show --query id --output tsv
if ($?) { Write-Host "📍 Subscription: $env:ARM_SUBSCRIPTION_ID" }
# Read the Anthropic key from a hidden prompt into the variable that Terraform reads
$env:TF_VAR_anthropic_api_key = Read-Host "Anthropic API key" -MaskInput
Write-Host "🔑 Anthropic key: in TF_VAR_anthropic_api_key ($($env:TF_VAR_anthropic_api_key.Length) characters, not shown)"
# Download the providers, then plan and apply the gateway, the Foundry model, the key, the Anthropic provider, its
# models, and the aliases
terraform init
if ($?) { terraform plan -out tfplan }
if ($?) { terraform apply tfplan }
if ($?) { Write-Host "🚀 Gateway deployed: $(terraform output -raw ai_gateway_url)" }Keep TF_VAR_anthropic_api_key in this terminal until you clean up: every terraform plan and terraform destroy
needs it, and so does terraform apply with a saved plan. In a new terminal, read it again with the same command.
The configuration deploys to eastus2. For another region where AI Gateway and the gpt-5-mini model are available,
as in Find the available regions, run export TF_VAR_location=<region>
(PowerShell: $env:TF_VAR_location = "<region>") before terraform plan. If your Claude Console key can't call the
default models, set TF_VAR_fast_model and TF_VAR_smart_model the same way.
Read the outputs and the key
Set the variables that the next sections and Verify use from the Terraform outputs, and read the gateway's runtime key, not the Anthropic key, from the gateway, so that it never shows on screen or lands in the Terraform state. Then move back to the lab's folder, which holds the scripts.
# Read the configuration's outputs: the gateway, the provider, the two models, and the runtime URL
export RG="$(terraform output -raw azure_resource_group)"
export GATEWAY="$(terraform output -raw ai_gateway_name)"
export PROVIDER="$(terraform output -raw anthropic_provider)"
export FAST_MODEL="$(terraform output -raw anthropic_fast_model)"
export SMART_MODEL="$(terraform output -raw anthropic_smart_model)"
export AI_GATEWAY_URL="$(terraform output -raw ai_gateway_url)"
echo "📝 Gateway $GATEWAY in $RG, provider $PROVIDER, models $FAST_MODEL and $SMART_MODEL"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"
# Read the gateway's runtime key from the gateway, so that it never lands in a file or the Terraform state
export AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets \
--ids "$(terraform output -raw ai_gateway_id)/apiKeys/app-first-call" --query primaryKey --output tsv)"
echo "🔑 Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"
# Move back to the lab's folder, then list the aliases that terraform apply created, with their backend models and
# token limits
cd .. && echo "📂 Lab folder: $(pwd)"
echo "🔖 Aliases on $GATEWAY:"
./infra/alias.sh list# Read the configuration's outputs: the gateway, the provider, the two models, the runtime URL, and the gateway's
# resource ID
$RG = terraform output -raw azure_resource_group
$GATEWAY = terraform output -raw ai_gateway_name
$PROVIDER = terraform output -raw anthropic_provider
$FAST_MODEL = terraform output -raw anthropic_fast_model
$SMART_MODEL = terraform output -raw anthropic_smart_model
$env:AI_GATEWAY_URL = terraform output -raw ai_gateway_url
$GATEWAY_ID = terraform output -raw ai_gateway_id
Write-Host "📝 Gateway $GATEWAY in $RG, provider $PROVIDER, models $FAST_MODEL and $SMART_MODEL"
Write-Host "🌐 Runtime URL: $env:AI_GATEWAY_URL"
# Read the gateway's runtime key from the gateway, so that it never lands in a file or the Terraform state
$env:AI_GATEWAY_API_KEY = az aigateway api-key list-secrets `
--ids "$GATEWAY_ID/apiKeys/app-first-call" --query primaryKey --output tsv
Write-Host "🔑 Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"
# Move back to the lab's folder, then list the aliases that terraform apply created, with their backend models and
# token limits
Set-Location ..
if ($?) { Write-Host "📂 Lab folder: $(Get-Location)" }
Write-Host "🔖 Aliases on ${GATEWAY}:"
./infra/alias.ps1 -ResourceGroup $RG -Gateway $GATEWAY listterraform apply ended with Apply complete! Resources: 15 added, 0 changed, 0 destroyed. The list shows
support-chat → anthropic/claude-haiku-5-5, batch-chat → anthropic/claude-haiku-5-5, and
anthropic/claude-sonnet-5-5 → anthropic/claude-sonnet-5-5, next to the quick start's gpt-5-mini →
foundry-models/gpt-5-mini.
Call Claude through the gateway
Send a native Anthropic Messages request to the gateway's Anthropic route. Three things differ from a direct
call to Anthropic: the URL is the gateway's, Authorization: Bearer carries your gateway runtime key, and model
is the alias. Keep the anthropic-version header that the Messages API expects.
# Call support-chat with the native Messages API: your runtime key as a bearer token, and the alias in model
curl -sS "${AI_GATEWAY_URL%/}/default/models/anthropic/v1/messages" \
-H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{"model": "support-chat", "max_tokens": 1024,
"messages": [{"role": "user", "content": "In one sentence, what is an AI gateway?"}]}' \
| jq -r 'if .content then
"✨ Backend model: \(.model)",
"🤖 \([.content[] | select(.type == "text") | .text] | join(""))",
"📊 Usage: \(.usage | tojson)"
else "🚨 \(.error.message // .)" end'# Build the request: your runtime key as a bearer token, the Messages API version, and the alias in model
$headers = @{ Authorization = "Bearer $env:AI_GATEWAY_API_KEY"; 'anthropic-version' = '2023-06-01' }
$body = @{
model = 'support-chat'
max_tokens = 1024
messages = @(@{ role = 'user'; content = 'In one sentence, what is an AI gateway?' })
} | ConvertTo-Json -Depth 5
# Call support-chat on the gateway's Anthropic route, and print the backend model, the reply, and the usage
$r = Invoke-RestMethod -Method Post -Uri "$($env:AI_GATEWAY_URL.TrimEnd('/'))/default/models/anthropic/v1/messages" `
-Headers $headers -ContentType 'application/json' -Body $body
if ($?) {
Write-Host "✨ Backend model: $($r.model)"
Write-Host "🤖 $((@($r.content) | Where-Object type -eq 'text' | ForEach-Object text) -join '')"
Write-Host "📊 Usage: $($r.usage | ConvertTo-Json -Compress)"
}The response uses Anthropic's own format, with content blocks, stop_reason, and usage.input_tokens. It
doesn't use OpenAI's choices. The model field names the backend model that answered, for example
claude-haiku-5-5. Claude Sonnet 5.5 and Haiku 5.5 think adaptively by default, so content can start
with a thinking block, and thinking counts toward max_tokens. Read the text blocks and leave headroom in
max_tokens.
The call prints a 🤖 Claude reply and ✨ Backend model: claude-haiku-5-5. Your app never sent an Anthropic
key.
To stream the reply, add "stream": true to the body and pass -N to curl. The gateway answers with
text/event-stream and forwards Anthropic's events as they arrive: message_start, content_block_delta,
message_delta, and message_stop. Streaming Anthropic Messages through the gateway works since the
November 6 release.
Give one backend model two aliases
The batch team's nightly job shouldn't be able to use up the capacity that the support app needs. Point a second
alias, batch-chat, at the same fast model and give each alias its own per-caller token limit: 2,000 tokens per
minute for batch-chat and 20,000 for support-chat. Alias policies apply only to callers that use that name.
Policies on the backend model apply to every alias that targets it.
Add the batch-chat alias
Select ModelsAliasesAdd alias. The Create alias wizard has seven steps:
| Step | What to do |
|---|---|
| Basics | Set Alias name to batch-chat and Description to Nightly batch summaries. |
| Auto model selection (preview) | Leave Choose a model based on the prompt off. |
| Select models | Select claude-haiku-5-5 from the Anthropic provider. The models of one alias must share an API format. |
| Session affinity | Keep the default. Session affinity needs several backend models. |
| Priorities and weights | Keep the defaults, priority 0 and weight 1. With one backend model, it gets all requests. |
| Failure handling | Keep the default, with no failure rules. |
| Review | Check the summary. |
Select Create. You can also start from ModelsAddAlias for existing models.
Limit each alias
Select PoliciesAdd policy. On the Type step, select Token rate limit under Cost and rate
limits, then Next. On the Scope step, select Individual assets, select the batch-chat alias, then
Next. On the Details step, set Time period to Per minute, Allowed tokens to 2000, and
Counter dimensions to Identity. Select Create.
Repeat for the support-chat alias with 20000 Allowed tokens.
In ModelsAliases, open batch-chat and select its Policies tab. It lists a Token rate limit
with the configuration 2,000 tokens / minute per caller identity and the scope This alias. The
support-chat alias lists 20,000 tokens / minute per caller identity.
Put both aliases with their limits
The optional fourth argument adds a per-caller token limit to the alias. It's the same tokenLimit policy
object that models use.
# Create batch-chat on the fast model, with a per-caller limit of 2,000 tokens per minute
./infra/alias.sh put batch-chat "$PROVIDER" "$FAST_MODEL" 2000 &&
echo "🔐 Token limit of 2,000 tokens per minute is on batch-chat"
# Give support-chat, on the same model, its own per-caller limit of 20,000 tokens per minute
./infra/alias.sh put support-chat "$PROVIDER" "$FAST_MODEL" 20000 &&
echo "🔐 Token limit of 20,000 tokens per minute is on support-chat"# Create batch-chat on the fast model, with a per-caller limit of 2,000 tokens per minute
./infra/alias.ps1 -ResourceGroup $RG -Gateway $GATEWAY put batch-chat $PROVIDER $FAST_MODEL 2000
if ($?) { Write-Host "🔐 Token limit of 2,000 tokens per minute is on batch-chat" }
# Give support-chat, on the same model, its own per-caller limit of 20,000 tokens per minute
./infra/alias.ps1 -ResourceGroup $RG -Gateway $GATEWAY put support-chat $PROVIDER $FAST_MODEL 20000
if ($?) { Write-Host "🔐 Token limit of 20,000 tokens per minute is on support-chat" }The command now passes a policy in --policies:
[ { "type": "tokenLimit", "count": 2000, "period": "minute", "counterKey": ["identity"] } ]put replaces the alias's whole policies list, so a put without a limit removes it. To change only the
target, use retarget in the next section.
Each command prints the alias with tokenLimit 2000/minute or tokenLimit 20000/minute.
Check the declared limits
azd up already created batch-chat and both limits: anthropic-aliases.bicep declares each alias with a
tokenLimit policy, the same object that the Azure CLI track passes in --policies. Show the batch-chat alias.
# Show the policies that the template declared on the batch-chat alias
echo "🔐 Policies on batch-chat:"
./infra/alias.sh show batch-chat | jq '.properties.policies'# Show the policies that the template declared on the batch-chat alias
Write-Host "🔐 Policies on batch-chat:"
(./infra/alias.ps1 -ResourceGroup $RG -Gateway $GATEWAY show batch-chat | ConvertFrom-Json).properties.policiesTo change a limit, set BATCH_CHAT_TOKENS_PER_MINUTE or SUPPORT_CHAT_TOKENS_PER_MINUTE with azd env set, then
run azd provision.
The output lists one tokenLimit policy with "count": 2000, "period": "minute", and
"counterKey": ["identity"].
Check the declared limits
terraform apply already created batch-chat and both limits: anthropic-aliases.tf declares each alias with a
tokenLimit policy, the same object that the Azure CLI track passes in --policies. Show the batch-chat alias.
# Show the policies that the configuration declared on the batch-chat alias
echo "🔐 Policies on batch-chat:"
./infra/alias.sh show batch-chat | jq '.properties.policies'# Show the policies that the configuration declared on the batch-chat alias
Write-Host "🔐 Policies on batch-chat:"
(./infra/alias.ps1 -ResourceGroup $RG -Gateway $GATEWAY show batch-chat | ConvertFrom-Json).properties.policiesTo change a limit, pass batch_chat_tokens_per_minute or support_chat_tokens_per_minute to terraform plan in the
Terraform folder, for example -var batch_chat_tokens_per_minute=5000, and apply the plan. Only that alias changes:
the plan ends with Plan: 0 to add, 1 to change, 0 to destroy. Pass the same -var to every later terraform plan,
or the plan sets the default back.
The output lists one tokenLimit policy with "count": 2000, "period": "minute", and
"counterKey": ["identity"].
Retarget an alias without touching clients
The support team wants better answers. Point support-chat at the bigger model. The clients keep sending
"model": "support-chat", and the alias keeps its 20,000-token limit.
Edit the alias
In ModelsAliases, open the support-chat alias and select Edit. Edit alias shows the sections
of Create alias on one page. Under Select models, clear claude-haiku-5-5 and select claude-sonnet-5-5
from the Anthropic provider, then select Save. New requests use the selected backend model within about
30 seconds.
Check that the policy stayed
On the support-chat alias page, select the Policies tab.
The alias page shows claude-sonnet-5-5 on the Backend models tab, and the Policies tab still lists the
20,000-token Token rate limit.
Update only the backend model
retarget runs az aigateway model-alias update with only --backend-model. The command changes only the
properties you pass, so the alias name, description, and policies stay as they are.
# Point support-chat at the bigger model, and keep its name, description, and token limit
./infra/alias.sh retarget support-chat "$PROVIDER" "$SMART_MODEL" &&
echo "🔖 Alias support-chat now points to $PROVIDER/$SMART_MODEL"# Point support-chat at the bigger model, and keep its name, description, and token limit
./infra/alias.ps1 -ResourceGroup $RG -Gateway $GATEWAY retarget support-chat $PROVIDER $SMART_MODEL
if ($?) { Write-Host "🔖 Alias support-chat now points to $PROVIDER/$SMART_MODEL" }az aigateway model-alias update -g <resource-group> --gateway-name <gateway> -n support-chat \
--backend-model resource-id=.../modelProviders/anthropic/models/claude-sonnet-5-5 --only-show-errors -o noneThe output shows support-chat → anthropic/claude-sonnet-5-5 and still tokenLimit 20000/minute.
Change the backend model in the environment
The template points support-chat at the model in SUPPORT_CHAT_MODEL, and the fast model when it's empty. Set it
to the bigger model and provision again. The deployment replaces the whole alias, but the template declares the
policy with it, so the limit stays.
# Point support-chat at the bigger model in the azd environment
azd env set SUPPORT_CHAT_MODEL "$SMART_MODEL" &&
echo "📝 SUPPORT_CHAT_MODEL is $SMART_MODEL"
# Deploy the template again: it replaces the alias, with the new backend model and the same token limit
azd provision &&
echo "🚀 Alias support-chat is deployed on $SMART_MODEL"
# List the aliases, to check the backend model and the token limit of support-chat
echo "🔖 Aliases on $GATEWAY:"
./infra/alias.sh list# Point support-chat at the bigger model in the azd environment
azd env set SUPPORT_CHAT_MODEL $SMART_MODEL
if ($?) { Write-Host "📝 SUPPORT_CHAT_MODEL is $SMART_MODEL" }
# Deploy the template again: it replaces the alias, with the new backend model and the same token limit
azd provision
if ($?) { Write-Host "🚀 Alias support-chat is deployed on $SMART_MODEL" }
# List the aliases, to check the backend model and the token limit of support-chat
Write-Host "🔖 Aliases on ${GATEWAY}:"
./infra/alias.ps1 -ResourceGroup $RG -Gateway $GATEWAY listThe output shows support-chat → anthropic/claude-sonnet-5-5 and still tokenLimit 20000/minute.
Change the backend model with a variable
The configuration points support-chat at the model in support_chat_model, and the fast model when it's empty. Pass
the bigger model to terraform plan and apply the plan. Terraform updates the alias with its whole body, but the
configuration declares the policy with it, so the limit stays.
# Move into the lab's Terraform folder
cd ~/aigateway/labs/03-multi-provider-aliases/terraform &&
echo "📂 Terraform folder: $(pwd)"
# Plan the change: only support-chat changes, to the bigger model
terraform plan -var "support_chat_model=$SMART_MODEL" -out tfplan &&
echo "📝 The plan updates only the support-chat alias"
# Apply the plan, then move back to the lab's folder
terraform apply tfplan &&
echo "🚀 Alias support-chat is deployed on $SMART_MODEL" &&
cd ..
# List the aliases, to check the backend model and the token limit of support-chat
echo "🔖 Aliases on $GATEWAY:"
./infra/alias.sh list# Move into the lab's Terraform folder
Set-Location ~/aigateway/labs/03-multi-provider-aliases/terraform
if ($?) { Write-Host "📂 Terraform folder: $(Get-Location)" }
# Plan the change: only support-chat changes, to the bigger model
terraform plan -var "support_chat_model=$SMART_MODEL" -out tfplan
if ($?) { Write-Host "📝 The plan updates only the support-chat alias" }
# Apply the plan, then move back to the lab's folder
terraform apply tfplan
if ($?) { Write-Host "🚀 Alias support-chat is deployed on $SMART_MODEL"; Set-Location .. }
# List the aliases, to check the backend model and the token limit of support-chat
Write-Host "🔖 Aliases on ${GATEWAY}:"
./infra/alias.ps1 -ResourceGroup $RG -Gateway $GATEWAY listPass the same -var to every later terraform plan: without it, the plan points support-chat back at the fast
model. support_chat_model takes only the fast or the bigger model, so a plan with another model stops with
support_chat_model takes an empty string, fast_model, or smart_model.
The plan ended with Plan: 0 to add, 1 to change, 0 to destroy., for
azapi_resource.anthropic_alias["support-chat"]. The output shows support-chat → anthropic/claude-sonnet-5-5
and still tokenLimit 20000/minute.
Retarget only between backend models that support the same interface. An alias that clients call with the Anthropic Messages API must keep pointing to a model that supports Anthropic Messages.
Verify
List the aliases
# List the aliases, with their backend models and token limits
echo "🔖 Aliases on $GATEWAY:"
./infra/alias.sh list# List the aliases, with their backend models and token limits
Write-Host "🔖 Aliases on ${GATEWAY}:"
./infra/alias.ps1 -ResourceGroup $RG -Gateway $GATEWAY listExpected output (the order and your Foundry alias differ):
🔖 Aliases on <gateway>:
ALIAS PROVIDER/BACKEND MODEL ALIAS POLICIES
anthropic/claude-sonnet-5-5 anthropic/claude-sonnet-5-5 -
batch-chat anthropic/claude-haiku-5-5 tokenLimit 2000/minute
contoso-ai/gpt-5-mini contoso-ai/gpt-5-mini -
support-chat anthropic/claude-sonnet-5-5 tokenLimit 20000/minuteYour Foundry and Anthropic models sit side by side behind one gateway. In the portal, Models shows the same list.
Call both aliases
The script sends a Messages request and prints the status, the backend model that answered, and the reply.
# Call each alias with the same Messages request, and print the backend model that answered
echo "🤖 Replies through support-chat and batch-chat:"
./infra/call-anthropic.sh support-chat
./infra/call-anthropic.sh batch-chat# Call each alias with the same Messages request, and print the backend model that answered
Write-Host "🤖 Replies through support-chat and batch-chat:"
./infra/call-anthropic.ps1 -Alias support-chat
./infra/call-anthropic.ps1 -Alias batch-chatOn GitHub, open call-anthropic.sh or call-anthropic.ps1.
Expected output (the replies differ):
🤖 Replies through support-chat and batch-chat:
Alias: support-chat
Status: 200
Model: claude-sonnet-5-5
Reply: An AI gateway is a control point between applications and AI models that ...
Alias: batch-chat
Status: 200
Model: claude-haiku-5-5
Reply: An AI gateway sits between your apps and AI models to ...support-chat now answers with Sonnet and batch-chat with Haiku, and you didn't change the client request.
Confirm the alias kept its policy
# Show the policies on support-chat, which kept its token limit when you retargeted it
echo "🔐 Policies on support-chat:"
./infra/alias.sh show support-chat | jq '.properties.policies'# Show the policies on support-chat, which kept its token limit when you retargeted it
Write-Host "🔐 Policies on support-chat:"
(./infra/alias.ps1 -ResourceGroup $RG -Gateway $GATEWAY show support-chat | ConvertFrom-Json).properties.policiesThe output lists the tokenLimit policy with "count": 20000 and "counterKey": ["identity"]. In the portal,
open support-chat and select Policies.
Go further
Use the Anthropic SDK. Point the SDK at the gateway's Anthropic base URL, and pass the runtime key as
auth_token, which the SDK sends asAuthorization: Bearer. The SDK appends/v1/messagesitself and sendsanthropic-versionfor you.Pythonimport os from anthropic import Anthropic # pip install anthropic client = Anthropic( base_url=os.environ["AI_GATEWAY_URL"].rstrip("/") + "/default/models/anthropic", auth_token=os.environ["AI_GATEWAY_API_KEY"], # sent as Authorization: Bearer ) message = client.messages.create( model="support-chat", max_tokens=1024, messages=[{"role": "user", "content": "Hello"}], ) print(message.model, "".join(block.text for block in message.content if block.type == "text"))Move one alias between providers. Add OpenAI as a second custom provider with the values from the provider table, and register
gpt-5-miniwith the OpenAI Chat Completions API format. Create an alias such asteam-chaton your Foundrygpt-5-mini, then retarget it to the OpenAI model. Both speak Chat Completions, so clients don't notice the switch.Layer the limits. Add a token limit to the
claude-haiku-5-5backend model as in Throttle tokens per caller with token limits. It applies to every alias that targets the model, on top of each alias's own limit.Read the product docs. Model API formats and providers lists the supported APIs and providers, and Create and update a model alias covers every step of the alias wizard.
Clean up
Keep the gateway, the runtime key, and the Foundry model from lab 02. Later labs use them.
Delete the aliases, models, and provider
Remove what you added in this lab in this order: aliases, then backend models, then the provider. Open each of the
support-chat, batch-chat, and anthropic/claude-sonnet-5-5 aliases in Models and delete them. Then delete
the two Claude backend models and the Anthropic provider.
Delete the aliases, models, and provider
Remove what you added in this lab in this order: aliases, then backend models, then the provider.
# Delete the three aliases first, because an alias points to a backend model
for ALIAS in support-chat batch-chat "$PROVIDER/$SMART_MODEL"; do ./infra/alias.sh delete "$ALIAS" && echo "🚮 Alias $ALIAS is deleted"; done
# Delete the two Claude backend models, then the provider that publishes them
for MODEL in "$FAST_MODEL" "$SMART_MODEL"; do
az aigateway model delete -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" --yes &&
echo "🚮 Backend model $MODEL is deleted"
done
az aigateway model-provider delete -g "$RG" --gateway-name "$GATEWAY" -n "$PROVIDER" --yes &&
echo "🚮 Model provider $PROVIDER is deleted"# Delete the three aliases first, because an alias points to a backend model
foreach ($alias in 'support-chat', 'batch-chat', "$PROVIDER/$SMART_MODEL") {
./infra/alias.ps1 -ResourceGroup $RG -Gateway $GATEWAY delete $alias
if ($?) { Write-Host "🚮 Alias $alias is deleted" }
}
# Delete the two Claude backend models, then the provider that publishes them
foreach ($model in $FAST_MODEL, $SMART_MODEL) {
az aigateway model delete -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER -n $model --yes
if ($?) { Write-Host "🚮 Backend model $model is deleted" }
}
az aigateway model-provider delete -g $RG --gateway-name $GATEWAY -n $PROVIDER --yes
if ($?) { Write-Host "🚮 Model provider $PROVIDER is deleted" }Delete everything azd created
In the aigateway/labs/03-multi-provider-aliases folder, delete the resource group with the gateway, the Foundry
account, and the Anthropic provider. --purge also purges the soft-deleted
Foundry account. It takes about three minutes. Then remove the azd environment, so that the Anthropic key doesn't stay
in .azure/aigw-lab03/.env.
# Delete the resource group with everything that azd up created, and purge the Foundry account
azd down --purge --force &&
echo "🚮 Everything that azd up created is deleted"
# Remove the azd environment, with the Anthropic key in its .env file
azd env remove aigw-lab03 --force &&
echo "🚮 azd environment aigw-lab03 is removed"azd down doesn't touch the gateway from earlier labs, because the Bicep + azd track created its own gateway.
Delete everything Terraform created
Delete the resource group with the gateway, the Foundry account, and the Anthropic provider. The
azurerm provider also purges the soft-deleted Foundry account. It takes
about two minutes. terraform destroy needs the Anthropic key variable too: the commands read it again if this
terminal doesn't have it, then clear it.
# Move into the lab's Terraform folder, and select the subscription that you deployed to
cd ~/aigateway/labs/03-multi-provider-aliases/terraform &&
echo "📂 Terraform folder: $(pwd)"
export ARM_SUBSCRIPTION_ID="$(az account show --query id --output tsv)"
# Read the Anthropic key again if this terminal doesn't have it: Terraform needs a value for every variable
[ -n "${TF_VAR_anthropic_api_key:-}" ] ||
{ printf "Anthropic API key: " && read -rs TF_VAR_anthropic_api_key && export TF_VAR_anthropic_api_key && echo; }
# Delete everything that terraform apply created, and purge the soft-deleted Foundry account
terraform destroy -auto-approve &&
echo "🚮 Everything that terraform apply created is deleted"
# Clear the Anthropic key from your shell
unset TF_VAR_anthropic_api_key &&
echo "🚮 TF_VAR_anthropic_api_key is cleared from this shell"# Move into the lab's Terraform folder, and select the subscription that you deployed to
Set-Location ~/aigateway/labs/03-multi-provider-aliases/terraform
if ($?) { Write-Host "📂 Terraform folder: $(Get-Location)" }
$env:ARM_SUBSCRIPTION_ID = az account show --query id --output tsv
# Read the Anthropic key again if this terminal doesn't have it: Terraform needs a value for every variable
if (-not $env:TF_VAR_anthropic_api_key) { $env:TF_VAR_anthropic_api_key = Read-Host "Anthropic API key" -MaskInput }
# Delete everything that terraform apply created, and purge the soft-deleted Foundry account
terraform destroy -auto-approve
if ($?) { Write-Host "🚮 Everything that terraform apply created is deleted" }
# Clear the Anthropic key from your shell
Remove-Item Env:TF_VAR_anthropic_api_key
if ($?) { Write-Host "🚮 TF_VAR_anthropic_api_key is cleared from this shell" }terraform destroy ended with Destroy complete! Resources: 15 destroyed.
terraform destroy doesn't touch the gateway from earlier labs, because the Terraform track created its own gateway.
Deleting the provider removes the stored Anthropic key from the gateway. It doesn't revoke the key itself. If you created the key only for this lab, delete it in the Claude Console.
Next steps
- Route an alias across models by priority and weight: canary a new model or prefer purchased capacity behind one alias.
- Throttle tokens per caller with token limits
- Enforce cost budgets with per-caller overrides
- Monitor usage, cost, and traces