Using az rest

How do you call the REST API using the az rest command?


The easiest way to test REST API calls is with the Azure CLI’s az rest command. The command simplifies the access token and also substitutes {subscriptionId}.

Here are the steps to read a resource group, delete it, recreate it and then update the tags.


The lab starts with an empty resource group.

  1. Log in using az login

  2. Check context using az account show

    You can switch context using az account set.

  3. Create a resource group

    az group create --name "myResourceGroup" --location "West Europe"

    Use a different resource group name if that already exists in your subscription.


There is no need to get the token with the az rest command.

  1. Authenticate with az login
  2. Check context with az account show

The CLI will cache the token in ~/.azure/msal_token_cache.json.

You can also display the token with az account get-access-token --query accessToken.

The token is a standard JSON web token. Paste the value into to view the claims.

See az login --help for examples if authenticating as a service principal or managed identity.


Another benefit of the az rest command is that {subscriptionId} in all of the references will be replace by the value of az account show --query id.

  1. View the Resource Groups - Get documentation

    See the example:

  2. Use az rest to get

    Note that if method is not specified then az rest defaults to GET.

    az rest --uri{subscriptionId}/resourcegroups/myResourceGroup?api-version=2021-04-01

    Example output:

      "id": "/subscriptions/2d31be49-d959-4415-bb65-8aec2c90ba62/resourceGroups/myResourceGroup",
      "location": "westeurope",
      "name": "myResourceGroup",
      "properties": {
        "provisioningState": "Succeeded"
      "type": "Microsoft.Resources/resourceGroups"

    Note that you can combine with standard –query and –output switches, e.g. az rest --uri $uri --query id --output tsv.


The delete uses the same uri. You specify the DELETE method.

  1. View the Resource Groups - Delete documentation

  2. Use az rest to delete

    az rest --method delete --uri{subscriptionId}/resourcegroups/myResourceGroup?api-version=2021-04-01

    Note that the command returns immediately. The az group delete command usually waits unless --no-wait is specified. You can check status using the get call.

Create or Update

The create uses PUT, and requires a request body.

  1. View the Resource Groups - Create Or Update documentation

    Use the In this article link to jump to the Request Body and the Examples

    The example JSON request body for resource groups is simple:

      "location": "westeurope"

    We will use more complex JSON to assign the new managedBy property using a variable.

  2. Set a variable for your objectId

    objectId=$(az ad signed-in-user show --query objectId --output tsv --only-show-errors)
  3. Use az rest to create

    az rest --method put --body "{\"location\":\"westeurope\",\"managedBy\":\"$objectId\"}"  --uri{subscriptionId}/resourcegroups/myResourceGroup?api-version=2021-04-01

    Note that the minified JSON for the --body switch is a double quoted string. The $objectId will be resolved. Using double quotes means that all quotes within the JSON need to be escaped with a backslash.

    If your request body string is literal then you can use single quotes, e.g. '{"location":"westeurope"}'.


The update uses PATCH and also requires a JSON request body. We’ll use a variable in the JSON and update the tags.

  1. View the Resource Groups - Update documentation

    Note the ResourceGroupPatchable section. This is a subset of the overall resource group properties.

    For instance, you cannot update the location as that would force a deletion and recreation for the resource group.

  2. Create variables

    It is common to use variables for the --uri and --body switches.

    owner="Your Name"
    body=$(cat <<EOF
      "tags": {
        "owner": "$owner",
        "site": "Azure Citadel"

    The last command uses a heredoc with a variable. There are other ways of dynamically generating JSON, e.g. jq.

  3. Use az rest to patch

    Update the tags.

    az rest --method patch --body "$body" --uri $uri

The resource group’s tags will be updated.


You have used the REST API via the Azure CLI’s az rest command to show, delete, recreate and update a resource.

Help us improve

Azure Citadel is a community site built on GitHub, please contribute and send a pull request

 Make a change