Azure AI Gateway Labs
Documentation Open portal
Foundations · Quick startNew

Your first model call in 5 minutes

Learn the building blocks of Azure AI Gateway, create a gateway with a Microsoft Foundry model in the portal, the Azure CLI, Bicep with azd, or Terraform, and make your first model call, all in about five minutes.

Beginner 5 min PortalCLIBicepTerraform Updated
Source Edit

What you'll do

  • Name the building blocks that every AI Gateway call goes through
  • Create a gateway, publish a Foundry model behind an alias, and create a runtime API key in the portal, the Azure CLI, Bicep with azd, or Terraform
  • Make your first model call through the gateway the way an app does, with an alias and a runtime API key

Before you start

No prerequisite labs. Start here.

Tracks: Portal, Azure CLI, Bicep + azd, Terraform

Azure AI Gateway gives your apps and agents one governed endpoint for models and tools. In five minutes you create a gateway, put a Microsoft Foundry model behind it, and call that model the way an app does: with the gateway's URL, an alias in the model field, and a runtime API key. Click through the AI Gateway portal, paste a few Azure CLI commands into Azure Cloud Shell, or clone a Bicep template or a Terraform configuration and deploy it with one azd up or terraform apply.

Before you begin

One-time setupThe Setup guide tasks that this lab uses. Mark each one done once, and the labs stop listing it.

Every later lab reuses this one-time setup. On the portal track, you need only Check your subscription and permissions.

  • Permissions to create resources and role assignments, for example Owner, or Contributor plus Role Based Access Control Administrator. The gateway gets a role on your Foundry account, so that it can call the model with its own identity.
  • A region where gpt-5-mini is available too, because the Azure CLI, Bicep + azd, and Terraform tracks create the Foundry account in the gateway's region. The examples use eastus2.

How it works

Every call that goes through AI Gateway uses the same building blocks. In this quick start you create one of each.

Building blockWhat it doesIn this quick start
GatewayThe Azure resource (Microsoft.ApiManagement/aigateways) that gives your apps one runtime URL for models and toolsYour gateway, at <gateway-url>
Model providerA connection to a backend. The gateway signs in to it with its own managed identity, so your apps never hold a backend keyYour Foundry account. The Azure CLI and Bicep tracks name the provider foundry-models
ModelA backend deployment that the gateway can route toThe Foundry deployment gpt-5-mini
AliasThe name that apps send in the model field. The gateway routes the alias to one or more models<foundry-account-name>/gpt-5-mini in the portal, gpt-5-mini in the Azure CLI and Bicep tracks
Runtime API keyIdentifies the app that calls the gateway, for limits, cost, and monitoring. Azure RBAC with Microsoft Entra ID tokens is the keyless alternativeapp-first-call

Your app calls the OpenAI-compatible base URL <gateway URL>/default/models/openai/v1, so any OpenAI SDK works with a different base URL and the runtime key. For the full tour, watch the 3-minute video in How Azure AI Gateway works.

Create a gateway and make your first call

Pick one track. Each one creates the same building blocks, makes your first call through the gateway, and ends with how to clean up.

Choose your track

What you need: a browser, and a model deployment in a Microsoft Foundry account, for example gpt-5-mini.

No Foundry deployment yet? Create one in Cloud Shell.

Open Azure Cloud Shell in Bash and paste these commands. They create a Foundry account with a gpt-5-mini deployment in a new resource group, in a minute or two. Then create the gateway in the same resource group, so that you can clean up with one command. Model inference is billed per use.

Bash
# Name the resource group, and give the Foundry account a random, globally unique name
RG="rg-aigw-quickstart"; FOUNDRY="aigw$(openssl rand -hex 3)"

# Create the resource group that holds the Foundry account and, later, the gateway
az group create --name "$RG" --location eastus2 --output none &&
  echo "📦 Resource group $RG is ready in eastus2"

# Create the Foundry account, with a custom subdomain so that the gateway can sign in with Microsoft Entra ID
az cognitiveservices account create --resource-group "$RG" --name "$FOUNDRY" --location eastus2 \
  --kind AIServices --sku S0 --custom-domain "$FOUNDRY" --yes --output none &&
  echo "🏭 Foundry account $FOUNDRY is ready"

# Deploy gpt-5-mini with 10,000 tokens per minute of Global Standard capacity
az cognitiveservices account deployment create --resource-group "$RG" --name "$FOUNDRY" \
  --deployment-name gpt-5-mini --model-name gpt-5-mini --model-version 2025-08-07 --model-format OpenAI \
  --sku-name GlobalStandard --sku-capacity 10 --output none &&
  echo "✨ Model deployment gpt-5-mini is ready"
echo "✅ Create the gateway in $RG, and import gpt-5-mini from $FOUNDRY"
1

Create the gateway

  1. Open the AI Gateway portal and sign in. For your first gateway, the portal opens Create AI gateway right away. Otherwise, open the gateway switcher in the top bar and select Create new gateway.

    The gateway switcher lists your recent gateways. Create new gateway opens the Create AI gateway dialog.
  2. Enter a Name, or select Generate a new name. Then choose your Subscription, a Resource group, and a Region. For the resource group, select New, or select Existing and pick the resource group of your Foundry account, so that you can clean up both with one command.

    Create AI gateway: a generated name, the existing resource group of the Foundry account, and East US 2.
  3. Keep the Advanced defaults and select Create gateway. All gateways opens and shows the Provisioning status, such as Created or InProgress, which moves to Succeeded in a few minutes. Then select your gateway's name to open it.

    All gateways while the gateway provisions. You can use other gateways while it runs.
2

Import the model from Foundry

  1. Home opens with the Set up your gateway guide. Under Add a model, select Add from Microsoft Foundry.

    Set up your gateway walks you through three steps: add a model, test a model, and apply policies.

    You can also start from ModelsAddModels from Microsoft Foundry.

    Models › Add imports models from Microsoft Foundry, AWS Bedrock, TypeSafe (Jev), or a custom provider, or creates an alias for models that you already added.
  2. Add models from Microsoft Foundry opens. It discovers the model deployments in your subscriptions and selects all of them. In Resource groups, select only the resource group of your Foundry account. Then check that Models shows 1 selected: your Foundry account with gpt-5-mini.

  3. Keep Managed identity as the Authentication method, with the system-assigned managed identity, and keep Create an alias for each model selected. Then select Add models.

    Filter by resource group, so that you import only the deployment that you need. The gateway calls Foundry with its managed identity.
  4. A banner confirms Models and aliases imported. Select Close: Models opens on the Backend models tab, which lists gpt-5-mini. The Aliases tab shows the alias that apps call: <foundry-account-name>/gpt-5-mini. Note the alias.

    Each alias is named after the Foundry account and the deployment, and routes to the backend model gpt-5-mini.
3

Create a runtime API key

A key is the quickest way to start. Azure RBAC is the keyless alternative: grant the app the AI Gateway Models User role in AccessEntra ID, and it sends a Microsoft Entra ID token instead of a key. Go keyless with Microsoft Entra ID and RBAC shows how.

  1. Select Access, then the API keys tab, then Create API key.

    Access › API keys lists the Built-in all-access API key and your keys. After the next step, app-first-call appears here.
  2. Enter app-first-call as the Key name, then select Create.

    Give the key a name that identifies the app. Limits, cost, and monitoring use it.
  3. In API key created, select Copy & done to copy the key. Keep it somewhere safe: you paste it in the next steps. You can view, rotate, or delete it later in AccessAPI keys.

    The key stays masked until you select Show. Copy & done copies it and closes the dialog.
4

Make your first call

Call the model through the gateway in the playground, with your new key, the way an app does.

  1. Select Catalog, then select your model.

    The Catalog lists the models and MCP servers that apps can call through this gateway.
  2. Under Authentication, check that Method is API key. Then change the API key from Built-in all-access API key to app-first-call, so that the playground calls the gateway with your new key. Send a prompt, for example In one sentence, what does an AI gateway do?.

    The playground calls the gateway's endpoint with the key that you choose, and shows the reply, the latency, the tokens, and the backend model.
  3. Optional: to make the same call from code, select Continue in code, then cURL. It shows the endpoint URL, your key masked, and snippets for cURL, the OpenAI SDK, LangChain, Vercel AI, the GitHub Copilot SDK, and Microsoft Agent Framework, plus a Coding agent prompt that installs the AI Gateway plugin.

    The cURL snippet has your gateway's URL and alias, and reads the key from the AI_GATEWAY_API_KEY environment variable.

To run the cURL snippet, open Azure Cloud Shell in Bash, paste your key at this prompt so that it never shows on screen, and then paste the snippet:

Bash
# Read the key without showing it, and export it for the snippet
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)"
Checkpoint:

the playground answered with the key app-first-call. Your gateway is live, and your app never needs a Foundry key: only the gateway's managed identity calls Foundry.

5

Clean up

To keep exploring, skip this step: lab 03 and the labs after it work on this gateway. On the labs site, save the resource group and the gateway name in Your values. Otherwise, delete the gateway.

  1. Open the gateway switcher in the top bar and select View all gateways.

  2. On your gateway's row, select More actions (…), and then select Delete.

    The More actions menu on a gateway's row: open the gateway in the Azure portal, copy its resource ID, or delete it.
  3. To confirm, select Delete in the dialog. The row shows Deleting until Azure removes the gateway, in about five minutes.

    Deleting a gateway removes its data: its models, aliases, keys, and policies. You can't undo it.

Deleting the gateway keeps its resource group and your Foundry account. If you created them in Cloud Shell for this quick start, delete the resource group and purge the Foundry account there too: deleted Foundry accounts stay soft-deleted for 48 hours and keep counting against your quota until you purge them.

Bash
# Find the Foundry account in the resource group, so that you can purge it after the delete
FOUNDRY="$(az cognitiveservices account list --resource-group rg-aigw-quickstart --query "[0].name" --output tsv)"
echo "🏭 Foundry account: $FOUNDRY"

# Delete the resource group, with everything in it
az group delete --name rg-aigw-quickstart --yes &&
  echo "🚮 Resource group rg-aigw-quickstart is deleted"

# Purge the deleted Foundry account, so that it stops counting against your quota
az cognitiveservices account purge --name "$FOUNDRY" --resource-group rg-aigw-quickstart --location eastus2 &&
  echo "🚮 Foundry account $FOUNDRY is purged"
Checkpoint:

after you refresh the page, All gateways no longer lists your gateway.

Next steps

Finished the lab?

Mark it complete to track your progress across paths. It's saved only in this browser.