Quickstart: Create a new Azure API Management service instance by using the Azure CLI (preview)

Azure API Management (APIM) helps organizations publish APIs to external, partner, and internal developers to unlock the potential of their data and services. API Management provides the core competencies to ensure a successful API program through developer engagement, business insights, analytics, security, and protection. APIM enables you to create and manage modern API gateways for existing backend services hosted anywhere. For more information, see the Overview.

This quickstart describes the steps for creating a new API Management instance using az apim commands in the Azure CLI. The commands in the az apim command group are currently in preview and may be changed or removed in a future release.

If you don't have an Azure subscription, create a free account before you begin.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Launch Cloud Shell in a new window
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block to copy the code.

  3. Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code.

You can use the Azure Cloud Shell or a local installation of the Azure CLI to complete this quickstart. If you'd like to use it locally, version 2.11.1 or later is recommended. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.

Create a resource group

Azure API Management instances, like all Azure resources, must be deployed into a resource group. Resource groups allow you to organize and manage related Azure resources.

First, create a resource group named myResourceGroup in the Central US location with the following az group create command:

az group create --name myResourceGroup --location centralus

Create a new service

Now that you have a resource group, you can create an API Management service instance. Create one by using the az apim create command and provide a service name and publisher details. The service name must be unique within Azure.

In the following example, myapim is used for the service name. Update the name to a unique value. Also update the name of the API publisher's organization and the email address to receive notifications.

az apim create --name myapim --resource-group myResourceGroup \
  --publisher-name Contoso --publisher-email admin@contoso.com \

By default, the command creates the instance in the Developer tier, an economical option to evaluate Azure API Management. This tier isn't for production use. For more information about scaling the API Management tiers, see upgrade and scale.


It can take between 30 and 40 minutes to create and activate an API Management service in this tier. The previous command uses the --no-wait option so that the command returns immediately while the service is created.

Check the status of the deployment by running the az apim show command:

az apim show --name myapim --resource-group myResourceGroup --output table

Initially, output is similar to the following, showing the Activating status:

-----------  ----------------  ----------  --------------  -----------  ------------  ----------  ---------  -------
myapim       myResourceGroup   Central US                                             Activating  Developer  1

After activation, the status is Online and the service instance has a gateway address and public IP address. For now, these addresses don't expose any content. For example:

-----------  ----------------  ----------  ---------------------------------  ------------  ------------  --------  ---------  -------
myapim       myResourceGroup   Central US  https://myapim.azure-api.net                 Online    Developer  1

When your API Management service instance is online, you're ready to use it. Start with the tutorial to import and publish your first API.

Clean up resources

When no longer needed, you can use the az group delete command to remove the resource group and the API Management service instance.

az group delete --name myResourceGroup

Next steps