Three callers now use your gateway: the app-dev web app, the support-bot agent, and a data scientist's
notebook that was shared with the whole company, key included. In this lab you give each caller its own runtime
API key, keep the values in a secret store, rotate the bot's key without taking it offline, and revoke the
leaked notebook key. Because every key is a separate caller identity, you can also see who used what.
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, model, and
keys, so you can skip this section. You need only the one-time setup above.
- Complete Provision your AI Gateway. You need the gateway, its resource group, and its runtime URL.
- Recommended: complete Publish a Foundry model and make your first call,
so you have a model alias to call. The checks in this lab call that alias. The gateway answers
404for an alias it doesn't know before it checks the key, so without a real alias the checks can't tell accepted keys from rejected keys. - Permission to manage the gateway's keys, for example Contributor on its resource group. Reading a key
value needs
Microsoft.ApiManagement/aigateways/apiKeys/listSecrets/action, which Contributor includes. - Optional: an Azure Key Vault that uses Azure RBAC, where you have Key Vault Secrets Officer. You can create one below.
- Optional, for usage and cost per key: monitoring configured in Monitor usage, cost, and traces.
- Run the scripts and samples from the lab's folder,
~/aigateway/labs/10-api-keys.
Set these variables once. Every track and the Verify section reuse them.
# Name your gateway, its resource group, and the model alias that the checks in this lab call
export RG="<resource-group>"
export GATEWAY="<gateway>"
export AI_GATEWAY_MODEL="<model-name>" # an alias you can call, for example the one from lab 02
# export KEY_VAULT="<key-vault>" # optional: uncomment to keep key values in Key Vault
# Read the gateway's runtime URL
export AI_GATEWAY_URL="https://$(az aigateway show -g "$RG" -n "$GATEWAY" --query properties.frontend.defaultHostname -o tsv)"
echo "๐ Gateway $GATEWAY in $RG, model alias $AI_GATEWAY_MODEL"
echo "๐ Runtime URL: $AI_GATEWAY_URL"# Name your gateway, its resource group, and the model alias that the checks in this lab call
$RG = "<resource-group>"
$GATEWAY = "<gateway>"
$env:AI_GATEWAY_MODEL = "<model-name>" # an alias you can call, for example the one from lab 02
# $KEY_VAULT = "<key-vault>" # optional: uncomment to keep key values in Key Vault
# Read the gateway's runtime URL
$env:AI_GATEWAY_URL = "https://$(az aigateway show -g $RG -n $GATEWAY --query properties.frontend.defaultHostname -o tsv)"
Write-Host "๐ Gateway $GATEWAY in $RG, model alias $env:AI_GATEWAY_MODEL"
Write-Host "๐ Runtime URL: $env:AI_GATEWAY_URL"No Key Vault yet? Create one for this lab.
Key Vault names are globally unique, 3 to 24 characters. The vault uses Azure RBAC, and you get Key Vault Secrets Officer so you can write and read secrets. A new role assignment can take a few minutes to apply.
# Name the vault with a random number, because Key Vault names are globally unique
export KEY_VAULT="kv-aigw-$RANDOM"
# Create the vault with Azure RBAC authorization, so that roles decide who can read its secrets
az keyvault create -g "$RG" -n "$KEY_VAULT" --enable-rbac-authorization true -o none &&
echo "โ
Key Vault is ready in $RG, and KEY_VAULT holds its name"
# Give yourself the Key Vault Secrets Officer role on the vault, so that you can write and read secrets
az role assignment create --role "Key Vault Secrets Officer" \
--assignee "$(az ad signed-in-user show --query id -o tsv)" \
--scope "$(az keyvault show -n "$KEY_VAULT" --query id -o tsv)" -o none &&
echo "๐ You're a Key Vault Secrets Officer on the vault (it can take a few minutes to apply)"# Name the vault with a random number, because Key Vault names are globally unique
$KEY_VAULT = "kv-aigw-$(Get-Random -Maximum 99999)"
# Create the vault with Azure RBAC authorization, so that roles decide who can read its secrets
az keyvault create -g $RG -n $KEY_VAULT --enable-rbac-authorization true -o none
if ($?) { Write-Host "โ
Key Vault is ready in $RG, and KEY_VAULT holds its name" }
# Give yourself the Key Vault Secrets Officer role on the vault, so that you can write and read secrets
az role assignment create --role "Key Vault Secrets Officer" `
--assignee (az ad signed-in-user show --query id -o tsv) `
--scope (az keyvault show -n $KEY_VAULT --query id -o tsv) -o none
if ($?) { Write-Host "๐ You're a Key Vault Secrets Officer on the vault (it can take a few minutes to apply)" }How it works
A runtime API key is a gateway resource with a name and two values, primary and secondary.
Both values work at the same time, which is what makes rotation without downtime possible. Clients send either
value as Authorization: Bearer <key>, which is how OpenAI SDKs send their API key, or in an api-key header. The
gateway validates the key before it applies policies or forwards the request, so a missing, wrong, rotated, or
deleted value, or a suspended key, gets 401 Unauthorized and never reaches a model. The 401 message is the same
one that Microsoft Entra ID callers get: Unauthorized. Missing or invalid Entra ID token, or missing Data.All scope.
A key is gateway-scoped: it grants access to every published model and MCP server on the gateway. Each key is also a separate caller identity, which token limits, cost limits, and Monitoring use to tell callers apart. That's why every app, agent, or user should get its own key.
| Task | Portal (AccessAPI keys) | Azure CLI (az aigateway api-key) | Bicep (aigateways/apiKeys) |
|---|---|---|---|
| Create a key | Create API key | create | Declare the key |
| Read a value | View keys (primary value) | list-secrets (primary and secondary values) | โ (never an output) |
| Rotate | Rotate key (primary value) | regenerate --key-type primary or --key-type secondary | โ |
| Block temporarily | โ | update --state suspended, then --state active | โ |
| Revoke | Delete | delete | โ (removing the key from the template doesn't delete it) |
The gateway also has a built-in key named master. Don't hand it out; create named keys instead.
Create a key for each app
Create three keys: app-dev for the web app, support-bot for the agent, and old-notebook, which stands in
for the key that leaked. Pick one track.
Create the first key
- In the AI Gateway portal, open your gateway and select AccessAPI keys.
- Select Create API key.
- In Key name, enter
app-dev, and select Create. - The API key created dialog shows the value. Select Copy & done.
Store the value right away; the next section shows where. After you close the dialog, only people with the
apiKeys/listSecrets/action permission, such as Contributors, can display the value again, with View keys.
Create the other two keys
Repeat the steps for support-bot and old-notebook. Names must be unique, ignoring case; a duplicate gets
A key named "..." already exists. The portal derives the key's resource name from Key name: lowercase, with
every character other than letters, digits, and hyphens replaced by -. Use that resource name with the CLI.
Load a value in your shell
Select the โฆ (More actions) button on the app-dev row, select View keys, and copy the value. Paste it
into your shell for the checks in this lab:
# Paste the key without showing it, and export it for the checks in this lab
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)"# Paste the key without showing it, and keep it in an environment variable for the checks in this lab
$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)"Create the keys
create sets each key's display name to its name. Commands identify a key by name, so use the name, not the
display name, in later commands.
# Create one runtime API key for each caller: the web app, the agent, and the notebook whose key leaks
for KEY in app-dev support-bot old-notebook; do
az aigateway api-key create -g "$RG" --gateway-name "$GATEWAY" -n "$KEY" -o none &&
echo "๐ API key $KEY is ready"
done
# List the gateway's keys and their state, without their values
echo "๐ API keys on $GATEWAY:"
az aigateway api-key list -g "$RG" --gateway-name "$GATEWAY" --query "[].{name:name, state:properties.state}" -o table# Create one runtime API key for each caller: the web app, the agent, and the notebook whose key leaks
foreach ($key in "app-dev", "support-bot", "old-notebook") {
az aigateway api-key create -g $RG --gateway-name $GATEWAY -n $key -o none
if ($?) { Write-Host "๐ API key $key is ready" }
}
# List the gateway's keys and their state, without their values
Write-Host "๐ API keys on ${GATEWAY}:"
az aigateway api-key list -g $RG --gateway-name $GATEWAY --query "[].{name:name, state:properties.state}" -o tableThe list also shows the built-in master key, and every key is active. create, list, and show never
return key values.
Load a value in your shell
az aigateway api-key list-secrets returns primaryKey and secondaryKey. Capture the value in a variable
instead of printing it:
# Read the primary value of the app-dev key into an environment variable, without showing it
export AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets -g "$RG" --gateway-name "$GATEWAY" -n app-dev \
--query primaryKey -o tsv)"
echo "๐ Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"# Read the primary value of the app-dev key into an environment variable, without showing it
$env:AI_GATEWAY_API_KEY = az aigateway api-key list-secrets -g $RG --gateway-name $GATEWAY -n app-dev `
--query primaryKey -o tsv
Write-Host "๐ Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"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
A key is a child resource of the gateway, Microsoft.ApiManagement/aigateways/apiKeys, so a template can declare
which keys exist. Their values aren't in the template: the gateway generates them, and a later deployment keeps
them. Rotating and revoking a key are operations, not declarations, so you run them with the Azure CLI in the next
sections.
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
app-first-call key, so the checks have an alias to call. Then it calls infra/api-keys.bicep with the key names:
// Lab 10 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 a runtime API key for each caller. Key values are never outputs.
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
@description('Key names, one for each caller. azd reads them from AI_GATEWAY_API_KEYS, a JSON array.')
param apiKeyNames array = [
'app-dev'
'support-bot'
'old-notebook'
]
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 apiKeys 'api-keys.bicep' = {
name: 'aigw-api-keys'
scope: rg
params: {
gatewayName: base.outputs.gatewayName
apiKeyNames: apiKeyNames
}
}
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 AI_GATEWAY_API_KEY_NAMES array = apiKeys.outputs.apiKeyNamesinfra/api-keys.bicep declares one key for each name. It only references the gateway, so you can also deploy it on
its own to a gateway you already have, with az deployment group create:
// Creates one runtime API key for each caller of an existing AI Gateway. 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. Each key is a separate
// caller identity in metrics and logs, and the gateway generates its primary and secondary values. Key values are
// never outputs: read them with "az aigateway api-key list-secrets", which needs the
// Microsoft.ApiManagement/aigateways/apiKeys/listSecrets/action permission.
@description('Name of the existing AI Gateway (Microsoft.ApiManagement/aigateways).')
param gatewayName string
@description('Key names, one for each caller. Names must be unique, ignoring case.')
param apiKeyNames array = [
'app-dev'
'support-bot'
'old-notebook'
]
#disable-next-line BCP081
resource gateway 'Microsoft.ApiManagement/aigateways@2026-11-01' existing = {
name: gatewayName
}
// Redeploying keeps each key's values: rotation and revocation are operations, not part of the template.
#disable-next-line BCP081
resource apiKeys 'Microsoft.ApiManagement/aigateways/apiKeys@2026-11-01' = [for name in apiKeyNames: {
parent: gateway
name: name
properties: {
// Keep the display name the same as the key's name, which the CLI and the scripts use.
displayName: name
}
}]
output apiKeyNames array = [for (name, i) in apiKeyNames: apiKeys[i].name]
output apiKeyIds array = [for (name, i) in apiKeyNames: apiKeys[i].id]Deploy with azd up
Move into the lab's folder, create an azd environment named aigw-lab10 in your current subscription, then provision
everything. It takes about three minutes.
# Move into the lab's folder, which holds the azd project
cd ~/aigateway/labs/10-api-keys &&
echo "๐ Lab folder: $(pwd)"
# Create an azd environment named aigw-lab10 in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab10 --location eastus2 --subscription "$(az account show --query id --output tsv)" &&
echo "๐ azd environment aigw-lab10 deploys to eastus2"
# Provision the gateway, the Foundry model, its alias, and the runtime API keys
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/10-api-keys
if ($?) { Write-Host "๐ Lab folder: $(Get-Location)" }
# Create an azd environment named aigw-lab10 in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab10 --location eastus2 --subscription (az account show --query id --output tsv)
if ($?) { Write-Host "๐ azd environment aigw-lab10 deploys to eastus2" }
# Provision the gateway, the Foundry model, its alias, and the runtime API keys
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.
Read the outputs and the key
Set the variables that the next sections and Verify use from azd's environment values, and read the app-dev
key from the gateway, so that it never shows on screen.
# Read azd's outputs into the variables that the next sections use
export RG="$(azd env get-value AZURE_RESOURCE_GROUP)"
export GATEWAY="$(azd env get-value AI_GATEWAY_NAME)"
export AI_GATEWAY_MODEL="$(azd env get-value AI_GATEWAY_MODEL)"
export GATEWAY_ID="$(azd env get-value AI_GATEWAY_ID)"
export AI_GATEWAY_URL="$(azd env get-value AI_GATEWAY_URL)"
echo "๐ Gateway $GATEWAY in $RG, model alias $AI_GATEWAY_MODEL"
echo "๐ Runtime URL: $AI_GATEWAY_URL"
# Read the app-dev 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 "$GATEWAY_ID/apiKeys/app-dev" \
--query primaryKey --output tsv)"
echo "๐ Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"
# List the gateway's keys and their state, without their values
echo "๐ API keys on $GATEWAY:"
az aigateway api-key list -g "$RG" --gateway-name "$GATEWAY" --query "[].{name:name, state:properties.state}" -o table# Read azd's outputs into the variables that the next sections use
$RG = azd env get-value AZURE_RESOURCE_GROUP
$GATEWAY = azd env get-value AI_GATEWAY_NAME
$env:AI_GATEWAY_MODEL = azd env get-value AI_GATEWAY_MODEL
$GATEWAY_ID = azd env get-value AI_GATEWAY_ID
$env:AI_GATEWAY_URL = azd env get-value AI_GATEWAY_URL
Write-Host "๐ Gateway $GATEWAY in $RG, model alias $env:AI_GATEWAY_MODEL"
Write-Host "๐ Runtime URL: $env:AI_GATEWAY_URL"
# Read the app-dev 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 "$GATEWAY_ID/apiKeys/app-dev" `
--query primaryKey --output tsv
Write-Host "๐ Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"
# List the gateway's keys and their state, without their values
Write-Host "๐ API keys on ${GATEWAY}:"
az aigateway api-key list -g $RG --gateway-name $GATEWAY --query "[].{name:name, state:properties.state}" -o tableazd up ended with SUCCESS. The table lists the built-in master key, the quick start's app-first-call,
and app-dev, support-bot, and old-notebook, all active.
Change the keys
The key names come from the AI_GATEWAY_API_KEYS environment value, a JSON array, with the default in
infra/main.parameters.json. To add a key, set the whole list and provision again. Existing keys keep their values.
# Set the whole list of key names, with a new batch-job key at the end
azd env set AI_GATEWAY_API_KEYS '["app-dev","support-bot","old-notebook","batch-job"]' &&
echo "๐ AI_GATEWAY_API_KEYS lists four keys, with batch-job"
# Provision again: azd creates batch-job, and the existing keys keep their values
azd provision &&
echo "๐ API key batch-job is ready, and the other keys keep their values"# Set the whole list of key names, with a new batch-job key at the end
azd env set AI_GATEWAY_API_KEYS '["app-dev","support-bot","old-notebook","batch-job"]'
if ($?) { Write-Host "๐ AI_GATEWAY_API_KEYS lists four keys, with batch-job" }
# Provision again: azd creates batch-job, and the existing keys keep their values
azd provision
if ($?) { Write-Host "๐ API key batch-job is ready, and the other keys keep their values" }Removing a name from the list doesn't delete the key: the deployment only creates and updates what the template declares. Delete a key with the CLI, as in Revoke a leaked key.
What you need: only the one-time setup from Before you begin, plus Terraform 1.9 or later, as in
Deploy a lab with Terraform. This track doesn't use your gateway from
earlier labs: terraform apply creates a new one, so it works on its own.
Choose what to declare
Like the Bicep templates, the configuration declares which keys exist, as Microsoft.ApiManagement/aigateways/apiKeys
resources. The gateway generates their values, so they never reach the Terraform state, and a later
terraform apply keeps them. Rotating and revoking a key are operations, not declarations, so you run them with the
Azure CLI in the next sections.
Review the configuration
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, so the checks have an alias to call:
# Lab 10 with Terraform: creates the resource group rg-<environment_name>, the quick start's gateway, Foundry model,
# default alias, and runtime API key, then one runtime API key for each caller in api_key_names (api-keys.tf). Key
# values are never outputs: read them with az aigateway api-key list-secrets.
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/api-keys.tf creates one key for each name in api_key_names, with the azapi provider, which sends the
AI Gateway API version, 2026-11-01, as is. terraform/variables.tf declares the names, with the same default as
the Bicep template:
# One runtime API key for each caller in api_key_names. Each key is a separate caller identity in metrics and logs,
# and the gateway generates its primary and secondary values, so they never reach the Terraform state. Rotation and
# suspension are operations, not configuration: terraform apply keeps each key's values and state. Removing a name
# from the list deletes that key.
resource "azapi_resource" "api_keys" {
for_each = toset(var.api_key_names)
type = "Microsoft.ApiManagement/aigateways/apiKeys@2026-11-01"
name = each.key
parent_id = module.base.gateway_id
body = {
properties = {
# Keep the display name the same as the key's name, which the CLI and the scripts use.
displayName = each.key
}
}
schema_validation_enabled = false
}Deploy with terraform apply
Move into the lab's Terraform folder, select your current subscription, then plan and apply the configuration. It takes about three minutes, most of it while the new gateway activates.
# Move into the lab's Terraform folder
cd ~/aigateway/labs/10-api-keys/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"
# Download the providers, then plan and apply the gateway, the Foundry model, its alias, and the runtime API keys
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/10-api-keys/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" }
# Download the providers, then plan and apply the gateway, the Foundry model, its alias, and the runtime API keys
terraform init
if ($?) { terraform plan -out tfplan }
if ($?) { terraform apply tfplan }
if ($?) { Write-Host "๐ Gateway deployed: $(terraform output -raw ai_gateway_url)" }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.
Read the outputs and the key
Set the variables that the next sections and Verify use from the Terraform outputs, and read the app-dev key
from the gateway, so that it never shows on screen or lands in the Terraform state.
# Read the configuration's outputs into the variables that the next sections use
export RG="$(terraform output -raw azure_resource_group)"
export GATEWAY="$(terraform output -raw ai_gateway_name)"
export AI_GATEWAY_MODEL="$(terraform output -raw ai_gateway_model)"
export GATEWAY_ID="$(terraform output -raw ai_gateway_id)"
export AI_GATEWAY_URL="$(terraform output -raw ai_gateway_url)"
echo "๐ Gateway $GATEWAY in $RG, model alias $AI_GATEWAY_MODEL"
echo "๐ Runtime URL: $AI_GATEWAY_URL"
# Read the app-dev 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 "$GATEWAY_ID/apiKeys/app-dev" \
--query primaryKey --output tsv)"
echo "๐ Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"
# List the gateway's keys and their state, without their values
echo "๐ API keys on $GATEWAY:"
az aigateway api-key list -g "$RG" --gateway-name "$GATEWAY" --query "[].{name:name, state:properties.state}" -o table# Read the configuration's outputs into the variables that the next sections use
$RG = terraform output -raw azure_resource_group
$GATEWAY = terraform output -raw ai_gateway_name
$env:AI_GATEWAY_MODEL = terraform output -raw ai_gateway_model
$GATEWAY_ID = terraform output -raw ai_gateway_id
$env:AI_GATEWAY_URL = terraform output -raw ai_gateway_url
Write-Host "๐ Gateway $GATEWAY in $RG, model alias $env:AI_GATEWAY_MODEL"
Write-Host "๐ Runtime URL: $env:AI_GATEWAY_URL"
# Read the app-dev 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-dev" `
--query primaryKey --output tsv
Write-Host "๐ Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"
# List the gateway's keys and their state, without their values
Write-Host "๐ API keys on ${GATEWAY}:"
az aigateway api-key list -g $RG --gateway-name $GATEWAY --query "[].{name:name, state:properties.state}" -o tableterraform apply ended with Apply complete! Resources: 12 added, 0 changed, 0 destroyed. The table lists the
built-in master key, the quick start's app-first-call, and app-dev, support-bot, and old-notebook, all
active.
Change the keys
The key names are the api_key_names variable, with the default in terraform/variables.tf. To add a key, pass the
whole list to terraform plan and apply the plan. Existing keys keep their values.
# Plan the change: the whole list of key names, with a new batch-job key at the end
terraform plan -var 'api_key_names=["app-dev","support-bot","old-notebook","batch-job"]' -out tfplan &&
echo "๐ The plan adds only batch-job"
# Apply the plan: Terraform creates batch-job, and the existing keys keep their values
terraform apply tfplan &&
echo "๐ API key batch-job is ready, and the other keys keep their values"# Plan the change: the whole list of key names, with a new batch-job key at the end
terraform plan -var 'api_key_names=["app-dev","support-bot","old-notebook","batch-job"]' -out tfplan
if ($?) { Write-Host "๐ The plan adds only batch-job" }
# Apply the plan: Terraform creates batch-job, and the existing keys keep their values
terraform apply tfplan
if ($?) { Write-Host "๐ API key batch-job is ready, and the other keys keep their values" }The plan ended with Plan: 1 to add, 0 to change, 0 to destroy., for azapi_resource.api_keys["batch-job"].
Unlike a Bicep deployment, Terraform deletes a key whose name leaves the list: the next plan without -var shows
Plan: 0 to add, 0 to change, 1 to destroy. for batch-job. Before you go on, plan and apply again without -var,
to go back to the default list.
The next sections and Verify run the scripts from the lab's folder, so move up to it:
cd .. (PowerShell: Set-Location ..).
From the lab folder, send one request with the app-dev key:
# Send one request with the app-dev key: the script prints the HTTP status, and only the key's last four characters
echo "๐ Expect 200 OK for the app-dev key:"
./infra/check-key.sh app-dev# Send one request with the app-dev key: the script prints the HTTP status, and only the key's last four characters
Write-Host "๐ Expect 200 OK for the app-dev key:"
./infra/check-key.ps1 -Label app-devThe script sends a tiny Chat Completions request and prints only the last four characters of the key. On GitHub, open check-key.sh or check-key.ps1.
#!/usr/bin/env bash
# Sends one small Chat Completions request through AI Gateway and reports whether the gateway accepted the
# runtime API key. Only the last four characters of the key are printed.
#
# Usage:
# export AI_GATEWAY_URL="<gateway-url>"
# export AI_GATEWAY_MODEL="<model-name>"
# export AI_GATEWAY_API_KEY="..." # the key to test; never commit it
# ./check-key.sh ["label"] # test AI_GATEWAY_API_KEY
# AI_GATEWAY_API_KEY="$OLD_KEY" ./check-key.sh "old value"
# ./check-key.sh --no-key # send the request without an Authorization header
# Requires curl.
set -euo pipefail
: "${AI_GATEWAY_URL:?Set AI_GATEWAY_URL to the gateway runtime URL, for example https://aigw-labs-k3v7qz2m9xw4p.eastus2-01.ai.gateway.azure.com}"
: "${AI_GATEWAY_MODEL:?Set AI_GATEWAY_MODEL to a callable model alias}"
URL="${AI_GATEWAY_URL%/}/default/models/openai/v1/chat/completions"
BODY=$(printf '{"model":"%s","messages":[{"role":"user","content":"ping"}]}' "$AI_GATEWAY_MODEL")
if [[ "${1:-}" == "--no-key" ]]; then
LABEL="no key"
HINT="-"
RESPONSE=$(curl -sS -w '\n%{http_code}' "$URL" \
-H "Content-Type: application/json" -d "$BODY" || true)
else
: "${AI_GATEWAY_API_KEY:?Set AI_GATEWAY_API_KEY to the runtime key to test}"
LABEL="${1:-current key}"
HINT="...${AI_GATEWAY_API_KEY: -4}"
# The header is read from stdin so the key doesn't appear in the process list.
RESPONSE=$(printf 'Authorization: Bearer %s\n' "$AI_GATEWAY_API_KEY" | curl -sS -w '\n%{http_code}' "$URL" \
-H @- -H "Content-Type: application/json" -d "$BODY" || true)
fi
STATUS="${RESPONSE##*$'\n'}"
case "$STATUS" in
2??) RESULT="accepted" ;;
401) RESULT="rejected: the key is missing, invalid, rotated, suspended, or deleted" ;;
404) if [[ "$RESPONSE" == *model_not_found* ]]; then
RESULT="not checked: the gateway doesn't know the alias in AI_GATEWAY_MODEL"
else
RESULT="key accepted, but the call failed: check AI_GATEWAY_MODEL and the gateway's policies"
fi ;;
000|"") RESULT="no response: check AI_GATEWAY_URL and your network"; STATUS="---" ;;
*) RESULT="key accepted, but the call failed: check AI_GATEWAY_MODEL and the gateway's policies" ;;
esac
printf '%-14s %-8s HTTP %s %s\n' "$LABEL" "$HINT" "$STATUS" "$RESULT"AccessAPI keys lists app-dev, support-bot, and old-notebook, and the check prints
HTTP 200 accepted for app-dev.
Send the key in either header
The gateway reads a runtime key from one of two headers. Use one per request; a request with both gets 400.
| Header | Used by |
|---|---|
Authorization: Bearer <key> | The docs, OpenAI SDKs, and the checks in this lab |
api-key: <key> | Azure OpenAI SDKs and tools that send an Azure OpenAI key |
Send the same request with each header, and then with both:
# Send the same request once with each header, and print only the HTTP status
URL="${AI_GATEWAY_URL%/}/default/models/openai/v1/chat/completions"
BODY="$(printf '{"model":"%s","messages":[{"role":"user","content":"ping"}]}' "$AI_GATEWAY_MODEL")"
for HEADER in "Authorization: Bearer" "api-key:"; do
# Read the header from stdin, so that the key doesn't appear in the process list
STATUS="$(printf '%s %s\n' "$HEADER" "$AI_GATEWAY_API_KEY" | curl -sS -o /dev/null -w '%{http_code}' "$URL" \
-H @- -H "Content-Type: application/json" -d "$BODY")"
echo "๐ ${HEADER%%:*} header: HTTP $STATUS"
done
# Send both headers in one request: the gateway rejects it with 400
echo "๐ฆ Expect 400 Bad Request for both headers:"
printf 'Authorization: Bearer %s\napi-key: %s\n' "$AI_GATEWAY_API_KEY" "$AI_GATEWAY_API_KEY" |
curl -sS "$URL" -H @- -H "Content-Type: application/json" -d "$BODY" -w '\nHTTP %{http_code}\n'# Send the same request once with each header, and print only the HTTP status
$uri = "$($env:AI_GATEWAY_URL.TrimEnd('/'))/default/models/openai/v1/chat/completions"
$body = @{ model = $env:AI_GATEWAY_MODEL; messages = @(@{ role = "user"; content = "ping" }) } | ConvertTo-Json -Depth 5
foreach ($headers in @{ "Authorization" = "Bearer $env:AI_GATEWAY_API_KEY" }, @{ "api-key" = $env:AI_GATEWAY_API_KEY }) {
$response = Invoke-WebRequest -Method Post -Uri $uri -Headers $headers -ContentType "application/json" `
-Body $body -SkipHttpErrorCheck
Write-Host "๐ $($headers.Keys) header: HTTP $($response.StatusCode)"
}
# Send both headers in one request: the gateway rejects it with 400
Write-Host "๐ฆ Expect 400 Bad Request for both headers:"
$both = @{ "Authorization" = "Bearer $env:AI_GATEWAY_API_KEY"; "api-key" = $env:AI_GATEWAY_API_KEY }
$response = Invoke-WebRequest -Method Post -Uri $uri -Headers $both -ContentType "application/json" `
-Body $body -SkipHttpErrorCheck
Write-Host "$($response.Content)`nHTTP $($response.StatusCode)"Both headers print HTTP 200, and the request with both prints HTTP 400 with
"Specify either an API key or an Authorization header, not both."
Store the key outside your code
A runtime key opens every model and MCP server on the gateway, so treat it like a password:
- Local development: set an environment variable for the session, as in this lab, and read it in code, for
example
os.environ["AI_GATEWAY_API_KEY"]in Python. If you keep it in a.envfile, add the file to.gitignore. - Hosted apps: keep the value in Azure Key Vault. App Service and Azure Functions resolve Key Vault references in app settings, and Azure Container Apps can reference Key Vault secrets.
- Pipelines: use the secret store of your CI system, or read the value from Key Vault at run time.
- Never put the value in source code, a committed
.envfile, build logs, notebooks, chat, or tickets.
If you set KEY_VAULT, store the app-dev and support-bot values there. The commands print only the secret
IDs. Each secret is named <key>-api-key, which is the name the rotation script updates later.
# Copy the primary value of each key into a Key Vault secret named <key>-api-key, and print only the secret IDs
echo "๐ Key Vault secret IDs:"
for KEY in app-dev support-bot; do
az keyvault secret set --vault-name "$KEY_VAULT" -n "$KEY-api-key" \
--value "$(az aigateway api-key list-secrets -g "$RG" --gateway-name "$GATEWAY" -n "$KEY" --query primaryKey -o tsv)" \
--tags aigateway-key="$KEY" key-type=primary --query id -o tsv
done# Copy the primary value of each key into a Key Vault secret named <key>-api-key, and print only the secret IDs
Write-Host "๐ Key Vault secret IDs:"
foreach ($key in "app-dev", "support-bot") {
$value = az aigateway api-key list-secrets -g $RG --gateway-name $GATEWAY -n $key --query primaryKey -o tsv
az keyvault secret set --vault-name $KEY_VAULT -n "$key-api-key" --value $value `
--tags aigateway-key=$key key-type=primary --query id -o tsv
}
# Clear the last key value from your session
Remove-Variable valueAn app, or you, then reads the value from the vault instead of from the gateway:
# Read the app-dev value from Key Vault instead of from the gateway, without showing it
export AI_GATEWAY_API_KEY="$(az keyvault secret show --vault-name "$KEY_VAULT" -n app-dev-api-key --query value -o tsv)"
echo "๐ Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"# Read the app-dev value from Key Vault instead of from the gateway, without showing it
$env:AI_GATEWAY_API_KEY = az keyvault secret show --vault-name $KEY_VAULT -n app-dev-api-key --query value -o tsv
Write-Host "๐ Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"The portal track can store the values the same way: run the commands above, or add the secrets to the vault in the Azure portal.
Rotate a key without downtime
Rotate keys on a schedule, and whenever someone who had a value leaves the team. Regenerating a value invalidates that value only, and right away. The trick is to regenerate the value that no client is using.
On the Bicep + azd and Terraform tracks, follow the Azure CLI track. A later azd provision or
terraform apply keeps the regenerated values.
Save the current value
You use the old value later to prove that it stopped working. On the support-bot row, select โฆ
(More actions) โบ View keys, copy the value, and paste it into your shell:
# Paste the current support-bot value without showing it, to prove later that the rotation retired it
printf "Current support-bot value: "; read -rs OLD_SUPPORT_BOT; echo
echo "๐ Current support-bot value: in OLD_SUPPORT_BOT (${#OLD_SUPPORT_BOT} characters, not shown)"# Paste the current support-bot value without showing it, to prove later that the rotation retired it
$OLD_SUPPORT_BOT = Read-Host "Current support-bot value" -MaskInput
Write-Host "๐ Current support-bot value: in OLD_SUPPORT_BOT ($($OLD_SUPPORT_BOT.Length) characters, not shown)"Rotate the key
- On the
support-botrow, select โฆ (More actions) โบ Rotate key. - The
Rotate "support-bot" key?dialog warns that clients using the old value get401 Unauthorizeduntil you update them. Select Rotate. - In API key rotated, copy the new value and update the client, or the
support-bot-api-keysecret in Key Vault.
The portal rotates the primary value in place, so a client that still sends the old value gets 401 until
you update it. To rotate without downtime from the portal, replace the key instead: create support-bot-v2,
move the client to it, and then delete support-bot. The new key is a new caller identity, so move any
cost-limit overrides to it, and expect Monitoring to report it separately. The CLI track avoids both trade-offs
with the secondary value.
Save the current value
Clients use the primary value today. Keep it so you can prove later that it stopped working:
# Save the primary value that clients use today, without showing it, to prove later that it stopped working
OLD_SUPPORT_BOT="$(az aigateway api-key list-secrets -g "$RG" --gateway-name "$GATEWAY" -n support-bot \
--query primaryKey -o tsv)"
echo "๐ Current primary value: in OLD_SUPPORT_BOT (${#OLD_SUPPORT_BOT} characters, not shown)"# Save the primary value that clients use today, without showing it, to prove later that it stopped working
$OLD_SUPPORT_BOT = az aigateway api-key list-secrets -g $RG --gateway-name $GATEWAY -n support-bot `
--query primaryKey -o tsv
Write-Host "๐ Current primary value: in OLD_SUPPORT_BOT ($($OLD_SUPPORT_BOT.Length) characters, not shown)"Regenerate the unused secondary value
No client uses the secondary value, so regenerating it breaks nothing:
# Regenerate the secondary value, which no client uses yet: the script shows only the last four characters of it
./infra/rotate-key.sh support-bot secondary &&
echo "๐ API key support-bot has a new secondary value, and clients on the primary keep working"# Regenerate the secondary value, which no client uses yet: the script shows only the last four characters of it
# To also update the support-bot-api-key secret, remove the # before -KeyVault
./infra/rotate-key.ps1 -ResourceGroup $RG -Gateway $GATEWAY -KeyName support-bot -KeyType secondary # -KeyVault $KEY_VAULT
if ($?) { Write-Host "๐ API key support-bot has a new secondary value, and clients on the primary keep working" }The script runs az aigateway api-key regenerate --key-type secondary, which replaces only the secondary value,
and reads the new value with az aigateway api-key list-secrets. It prints only the last four characters of the
new value. If KEY_VAULT is set in Bash, or you pass -KeyVault in PowerShell, it also
writes the new value to the support-bot-api-key secret. On GitHub, open rotate-key.sh or
rotate-key.ps1.
#!/usr/bin/env bash
# Regenerates one value (primary or secondary) of an AI Gateway runtime API key, reads the new value, and
# optionally stores it in Azure Key Vault. Only the last four characters of the key are printed.
#
# Zero-downtime rotation for clients that use the primary value today:
# ./rotate-key.sh support-bot secondary # 1. issue a fresh secondary value that no client uses yet
# # 2. move every client to the secondary value
# ./rotate-key.sh support-bot primary # 3. retire the old primary value
# Next time, swap the roles: regenerate primary first, move clients, then regenerate secondary.
#
# Usage:
# export RG="<resource-group>" GATEWAY="<gateway>"
# export KEY_VAULT="<key-vault-name>" # optional: store the new value as secret <key-name>-api-key
# ./rotate-key.sh <key-name> <primary|secondary>
# Requires the Azure CLI 2.75 or later with the aigateway extension.
set -euo pipefail
NAME="${1:?Usage: rotate-key.sh <key-name> <primary|secondary>}"
TYPE="${2:?Usage: rotate-key.sh <key-name> <primary|secondary>}"
case "$TYPE" in
primary|secondary) ;;
*) echo "error: the second argument must be primary or secondary" >&2; exit 2 ;;
esac
: "${RG:?Set RG to the gateway resource group}"
: "${GATEWAY:?Set GATEWAY to the gateway name}"
az aigateway api-key regenerate -g "$RG" --gateway-name "$GATEWAY" -n "$NAME" --key-type "$TYPE" -o none
VALUE="$(az aigateway api-key list-secrets -g "$RG" --gateway-name "$GATEWAY" -n "$NAME" --query "${TYPE}Key" -o tsv)"
if [[ -z "$VALUE" ]]; then
echo "error: couldn't read the new $TYPE value. You need the apiKeys/listSecrets/action permission." >&2
exit 1
fi
echo "Regenerated the $TYPE value of '$NAME' (ends in ...${VALUE: -4})."
if [[ -n "${KEY_VAULT:-}" ]]; then
SECRET="${NAME}-api-key"
az keyvault secret set --vault-name "$KEY_VAULT" --name "$SECRET" --value "$VALUE" \
--tags "aigateway-key=$NAME" "key-type=$TYPE" -o none
echo "Stored it in Key Vault '$KEY_VAULT' as secret '$SECRET'."
else
echo "Read it with: az aigateway api-key list-secrets -g $RG --gateway-name $GATEWAY -n $NAME --query ${TYPE}Key -o tsv"
fiMove the client to the secondary value
Update the client's configuration to the new secondary value and restart it, or let it reload the Key Vault secret. Both values are valid now, so no request fails during the switch. The old primary value still works:
# Check that the old primary value still works, so that clients can move over without failed requests
echo "๐ Expect 200 OK for the old primary value, until you regenerate it:"
AI_GATEWAY_API_KEY="$OLD_SUPPORT_BOT" ./infra/check-key.sh "old primary"# Check that the old primary value still works, so that clients can move over without failed requests
Write-Host "๐ Expect 200 OK for the old primary value, until you regenerate it:"
./infra/check-key.ps1 -ApiKey $OLD_SUPPORT_BOT -Label "old primary"Regenerate the primary value
When every client uses the secondary value, regenerate the primary. This invalidates the old value, wherever it might have been copied:
# Regenerate the primary value, so that the old value stops working wherever it was copied
./infra/rotate-key.sh support-bot primary &&
echo "๐ API key support-bot has a new primary value, and the old one stopped working"# Regenerate the primary value, so that the old value stops working wherever it was copied
# To also update the support-bot-api-key secret, remove the # before -KeyVault
./infra/rotate-key.ps1 -ResourceGroup $RG -Gateway $GATEWAY -KeyName support-bot -KeyType primary # -KeyVault $KEY_VAULT
if ($?) { Write-Host "๐ API key support-bot has a new primary value, and the old one stopped working" }Next time, rotate in the other direction: regenerate the primary, move clients to it, then regenerate the secondary. With Key Vault, the secret always holds the newest value, so clients that reload it move along automatically.
AI_GATEWAY_API_KEY="$OLD_SUPPORT_BOT" ./infra/check-key.sh "rotated value" (or
./infra/check-key.ps1 -ApiKey $OLD_SUPPORT_BOT -Label "rotated value") prints HTTP 401.
Revoke a leaked key
When a key leaks, revoke it first and investigate afterward. Deleting a key invalidates both of its values
within about 10 seconds, and anyone who holds them then gets 401. Pick one track.
On the Bicep + azd track, follow the Azure CLI track. Then remove old-notebook from the template's list, and
keep any names you added, so that a later azd provision doesn't create it again, with new values:
# Keep only the keys you still need in the list, so that a later azd provision doesn't create old-notebook again
azd env set AI_GATEWAY_API_KEYS '["app-dev","support-bot"]' &&
echo "๐ AI_GATEWAY_API_KEYS lists app-dev and support-bot"# Keep only the keys you still need in the list, so that a later azd provision doesn't create old-notebook again
azd env set AI_GATEWAY_API_KEYS '["app-dev","support-bot"]'
if ($?) { Write-Host "๐ AI_GATEWAY_API_KEYS lists app-dev and support-bot" }On the Terraform track, follow the Azure CLI track too, then come back and run this block. If you run it first,
Terraform deletes old-notebook before the CLI track saves its value for Verify. Plan without old-notebook, and
keep any names you added: a plan with the default list creates old-notebook again, with new values (Plan: 1 to add, 0 to change, 0 to destroy.). Pass the same list to every later plan, or change the default in
terraform/variables.tf:
# After the CLI deletes old-notebook, plan with only the keys you still need: the plan changes only an output
cd ~/aigateway/labs/10-api-keys/terraform &&
terraform plan -var 'api_key_names=["app-dev","support-bot"]' -out tfplan &&
terraform apply tfplan &&
echo "๐ Terraform manages app-dev and support-bot"
cd ..# After the CLI deletes old-notebook, plan with only the keys you still need: the plan changes only an output
Set-Location ~/aigateway/labs/10-api-keys/terraform
if ($?) { terraform plan -var 'api_key_names=["app-dev","support-bot"]' -out tfplan }
if ($?) { terraform apply tfplan }
if ($?) { Write-Host "๐ Terraform manages app-dev and support-bot" }
Set-Location ..Save the leaked value
You use it to prove that the key no longer works. On the old-notebook row, select โฆ (More actions) โบ
View keys, copy the value, and paste it into your shell:
# Paste the leaked value without showing it, to prove later that the gateway rejects it
printf "Leaked value: "; read -rs LEAKED_KEY; echo
echo "๐ Leaked value: in LEAKED_KEY (${#LEAKED_KEY} characters, not shown)"# Paste the leaked value without showing it, to prove later that the gateway rejects it
$LEAKED_KEY = Read-Host "Leaked value" -MaskInput
Write-Host "๐ Leaked value: in LEAKED_KEY ($($LEAKED_KEY.Length) characters, not shown)"Delete the key
Select the check box on the old-notebook row, and then select Delete. The Delete "old-notebook" key?
dialog warns that applications using the key will no longer authenticate to the gateway and that the action
can't be undone. Select Delete.
Save the leaked value and delete the key
# Save the leaked primary value without showing it, to prove later that the gateway rejects it
LEAKED_KEY="$(az aigateway api-key list-secrets -g "$RG" --gateway-name "$GATEWAY" -n old-notebook \
--query primaryKey -o tsv)"
echo "๐ Leaked value: in LEAKED_KEY (${#LEAKED_KEY} characters, not shown)"
# Delete the key: both of its values stop working within about 10 seconds
az aigateway api-key delete -g "$RG" --gateway-name "$GATEWAY" -n old-notebook --yes &&
echo "๐ฎ API key old-notebook is deleted"# Save the leaked primary value without showing it, to prove later that the gateway rejects it
$LEAKED_KEY = az aigateway api-key list-secrets -g $RG --gateway-name $GATEWAY -n old-notebook `
--query primaryKey -o tsv
Write-Host "๐ Leaked value: in LEAKED_KEY ($($LEAKED_KEY.Length) characters, not shown)"
# Delete the key: both of its values stop working within about 10 seconds
az aigateway api-key delete -g $RG --gateway-name $GATEWAY -n old-notebook --yes
if ($?) { Write-Host "๐ฎ API key old-notebook is deleted" }Suspend a key instead
To block a key while you investigate, without deleting it, set its state to suspended. Within about 10
seconds, calls with the key get 401 until you set it back to active. The Verify section expects
support-bot to work, so set it back to active before you continue:
# Suspend the support-bot key: calls with it get 401 until you set it back to active
STATE="$(az aigateway api-key update -g "$RG" --gateway-name "$GATEWAY" -n support-bot --state suspended \
--query properties.state -o tsv)" &&
echo "๐ API key support-bot is $STATE"
# Later, set the key back to active, so that it works again
STATE="$(az aigateway api-key update -g "$RG" --gateway-name "$GATEWAY" -n support-bot --state active \
--query properties.state -o tsv)" &&
echo "๐ API key support-bot is $STATE"# Suspend the support-bot key: calls with it get 401 until you set it back to active
$STATE = az aigateway api-key update -g $RG --gateway-name $GATEWAY -n support-bot --state suspended `
--query properties.state -o tsv
if ($?) { Write-Host "๐ API key support-bot is $STATE" }
# Later, set the key back to active, so that it works again
$STATE = az aigateway api-key update -g $RG --gateway-name $GATEWAY -n support-bot --state active `
--query properties.state -o tsv
if ($?) { Write-Host "๐ API key support-bot is $STATE" }The commands print the new state: ๐ API key support-bot is suspended, and then
๐ API key support-bot is active.
Then clean up after the leak: remove the value from the notebook and its history, and check Monitoring for calls made with the key.
If the caller behind a leaked key must keep its identity, for example because a cost-limit override or
Monitoring history is tied to it, regenerate both values instead of deleting the key. Run
./infra/rotate-key.sh <key> primary and then ./infra/rotate-key.sh <key> secondary (or the PowerShell
script with -KeyType), and give the caller the new value.
See usage and cost per key
Each key is a caller identity, so Monitoring can break usage down by key. This needs the monitoring setup from Monitor usage, cost, and traces and a few requests with each key.
- Select MonitoringModels.
- Active caller identities counts the API keys and Microsoft Entra identities with observed activity.
- Model usage by caller identity compares caller identities by estimated model cost, tokens, and calls.
- Use the All caller identities filter to scope the page to one key, for example
support-bot. Keys appear by name, marked API key.
The same identity drives enforcement. A Cost limit counted by Caller identity gives each key its own budget:
To set budgets and limits per key, continue with Enforce cost budgets with per-caller overrides.
When to move to Microsoft Entra ID
API keys are the fastest way to start, but the docs don't recommend them for production.
| Runtime API key | Microsoft Entra ID with Azure RBAC | |
|---|---|---|
| What the gateway sees | One named key | A user, agent, or workload identity in your tenant |
| What it can call | Every published model and MCP server | What its role grants: AI Gateway User (models and tools), AI Gateway Models User, or AI Gateway Tools User, on all assets, one alias, or one MCP server |
| Secret to protect | The key value | None with a managed identity; tokens are short-lived |
| Rotation | You rotate and redistribute values | Microsoft Entra ID issues new tokens |
| Good fit | Prototypes, labs, and tools that only accept a key | Production apps, agents, and per-user access |
Move to Microsoft Entra ID with Go keyless with Microsoft Entra ID and RBAC.
Verify
Run the checks from the lab folder. Only current values should get through; the rotated value, the deleted key,
and a request without a key should all get 401.
Load the app-dev key
If AI_GATEWAY_API_KEY no longer holds the app-dev value, load it again from Key Vault, with
az aigateway api-key list-secrets, or by pasting it, as in Create a key for each app.
Run the checks
# Check the current app-dev key, which the gateway accepts
echo "๐ Expect 200 OK for the app-dev key:"
./infra/check-key.sh app-dev
# Check the rotated value, the deleted key, and a request without a key: the gateway rejects all three
echo "๐ฆ Expect 401 Unauthorized for the rotated value, the deleted key, and no key:"
AI_GATEWAY_API_KEY="$OLD_SUPPORT_BOT" ./infra/check-key.sh "rotated value"
AI_GATEWAY_API_KEY="$LEAKED_KEY" ./infra/check-key.sh "deleted key"
./infra/check-key.sh --no-key# Check the current app-dev key, which the gateway accepts
Write-Host "๐ Expect 200 OK for the app-dev key:"
./infra/check-key.ps1 -Label app-dev
# Check the rotated value, the deleted key, and a request without a key: the gateway rejects all three
Write-Host "๐ฆ Expect 401 Unauthorized for the rotated value, the deleted key, and no key:"
./infra/check-key.ps1 -ApiKey $OLD_SUPPORT_BOT -Label "rotated value"
./infra/check-key.ps1 -ApiKey $LEAKED_KEY -Label "deleted key"
./infra/check-key.ps1 -NoKeyExpected output (your key endings differ):
๐ Expect 200 OK for the app-dev key:
app-dev ...Q7xk HTTP 200 accepted
๐ฆ Expect 401 Unauthorized for the rotated value, the deleted key, and no key:
rotated value ...m2Rd HTTP 401 rejected: the key is missing, invalid, rotated, suspended, or deleted
deleted key ...Vt9a HTTP 401 rejected: the key is missing, invalid, rotated, suspended, or deleted
no key - HTTP 401 rejected: the key is missing, invalid, rotated, suspended, or deletedCheck that the rotated key still works
Load a current support-bot value from View keys, Key Vault, or az aigateway api-key list-secrets, and run
the check again. After the CLI flow, both the new primary and the new secondary value work. The check prints
HTTP 200:
# Paste a current support-bot value without showing it
printf "Current support-bot value: "; read -rs SUPPORT_BOT; echo
echo "๐ Current support-bot value: in SUPPORT_BOT (${#SUPPORT_BOT} characters, not shown)"
# Check it: after the rotation, the gateway accepts both the new primary and the new secondary value
echo "๐ Expect 200 OK for the current support-bot value:"
AI_GATEWAY_API_KEY="$SUPPORT_BOT" ./infra/check-key.sh support-bot# Paste a current support-bot value without showing it
$SUPPORT_BOT = Read-Host "Current support-bot value" -MaskInput
Write-Host "๐ Current support-bot value: in SUPPORT_BOT ($($SUPPORT_BOT.Length) characters, not shown)"
# Check it: after the rotation, the gateway accepts both the new primary and the new secondary value
Write-Host "๐ Expect 200 OK for the current support-bot value:"
./infra/check-key.ps1 -ApiKey $SUPPORT_BOT -Label support-botGo further
- Prompt for the key in MCP clients. VS Code can ask for the key when it starts an MCP server instead of
storing it in
mcp.json. See Federate MCP tools behind one endpoint. - Get a rotation reminder. Set an expiry date on the Key Vault secret with
az keyvault secret set-attributes --expires, and subscribe to the vault'sSecretNearExpiryevent. - Automate rotation. Run the rotation script from a scheduled pipeline that signs in with a workload identity, with a pause between the secondary and primary steps for clients to reload.
- Limit each key. Give every key its own token allowance with Throttle tokens per caller with token limits.
Clean up
Keep app-dev and support-bot:
Enforce cost budgets with per-caller overrides gives them different budgets.
Delete the test keys
Delete any other keys you created for testing, such as support-bot-v2, in AccessAPI keys (check box,
then Delete).
Delete the test keys
Delete any other keys you created for testing, such as support-bot-v2:
# Delete a test key, for example support-bot-v2 from the portal's rotation
az aigateway api-key delete -g "$RG" --gateway-name "$GATEWAY" -n support-bot-v2 --yes &&
echo "๐ฎ API key support-bot-v2 is deleted"Delete everything azd created
In the aigateway/labs/10-api-keys folder, delete the resource group with the gateway, the Foundry account, and the
keys. --purge also purges the soft-deleted Foundry account. It takes a few
minutes.
# Delete everything that azd up created, and purge the Foundry account
azd down --purge --force &&
echo "๐ฎ Everything that azd up created is deleted"The Bicep + azd track of lab 07 creates its own app-dev and support-bot keys, so you don't need to keep these.
Delete everything Terraform created
In the aigateway/labs/10-api-keys/terraform folder, delete the resource group with the gateway, the Foundry
account, and the keys. The azurerm provider also purges the
soft-deleted Foundry account. It takes a few minutes.
# Delete everything that terraform apply created, and purge the soft-deleted Foundry account
cd ~/aigateway/labs/10-api-keys/terraform &&
terraform destroy -auto-approve &&
echo "๐ฎ Everything that terraform apply created is deleted"If you created a Key Vault only for this lab, delete it. Key Vault keeps deleted vaults for a retention period and reserves the name; purge it if you want to reuse the name right away:
# Delete the vault: Key Vault keeps it for a retention period, and reserves its name
az keyvault delete -n "$KEY_VAULT" &&
echo "๐ฎ Key Vault is deleted, and its name stays reserved until you purge it"
# Purge the deleted vault, so that you can reuse its name right away
az keyvault purge -n "$KEY_VAULT" &&
echo "๐ฎ Key Vault is purged"Clear the key values from your shell with unset AI_GATEWAY_API_KEY OLD_SUPPORT_BOT LEAKED_KEY SUPPORT_BOT
(Bash) or Remove-Variable OLD_SUPPORT_BOT, LEAKED_KEY, SUPPORT_BOT; Remove-Item Env:AI_GATEWAY_API_KEY
(PowerShell). Delete the gateway from earlier labs only when you finish all labs, as described in
Provision your AI Gateway. azd down and terraform destroy don't
touch it, because the Bicep + azd and Terraform tracks created their own gateway.
Next steps
- Go keyless with Microsoft Entra ID and RBAC: replace keys with identities and roles.
- Enforce cost budgets with per-caller overrides: give
app-devandsupport-botdifferent budgets. - Monitor usage, cost, and traces: see usage and cost for each key.
- Docs: Security and identity in AI Gateway and Authenticate with an API key.