Install the Azure API Management CLI

Install hiddenlayer-apim on a workstation or CI runner that can authenticate to Azure and reach your APIM instance.

Prerequisites

Azure CLI installed.
Azure CLI authenticated with az login.
An Azure identity assigned an APIM role with read and write access to APIs, API policies, named values, and policy fragments on the target APIM service. See Azure permissions below for the recommended role and the minimum action set for custom roles.
HiddenLayer client ID, client secret, project ID, and tenant ID.

Azure Permissions

The CLI calls the Azure Resource Manager APIM control plane on behalf of the signed-in identity. The signed-in identity must be able to read and write API policies, named values, and policy fragments on the target APIM service.

Recommended Built-In Role

Assign API Management Service Contributor (Microsoft.ApiManagement/service/*) to the identity running the CLI, scoped to the target APIM service, its parent resource group, or the subscription:

az role assignment create \
  --assignee "<user-or-service-principal>" \
  --role "API Management Service Contributor" \
  --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-name>"

The other built-in APIM roles are not sufficient:

API Management Service Reader grants only read access, so deploy, apply, and remove will fail.
API Management Service Operator can manage the APIM service itself but not its child entities, so it cannot create or update named values, policy fragments, or API policies.

Minimum Custom Role Actions

For least-privilege deployments, a custom role assigned at the APIM service scope must include at least these actions:

Microsoft.ApiManagement/service/read
Microsoft.ApiManagement/service/apis/read
Microsoft.ApiManagement/service/apis/policies/read
Microsoft.ApiManagement/service/apis/policies/write
Microsoft.ApiManagement/service/namedValues/read
Microsoft.ApiManagement/service/namedValues/write
Microsoft.ApiManagement/service/policyFragments/read
Microsoft.ApiManagement/service/policyFragments/write

Notes:

The CLI never reads the plaintext of secret named values, so the role does not need Microsoft.ApiManagement/service/namedValues/listValue/action.
For background on built-in APIM roles and custom-role authoring, see the Microsoft docs on role-based access control in Azure API Management.

Install From a Release

Download the latest release for your operating system from the HiddenLayer Azure APIM Guardrails release page. Release assets are published as versioned archives:

macOS: hiddenlayer-apim-vX.Y.Z-darwin-arm64.pkg or hiddenlayer-apim-vX.Y.Z-darwin-amd64.pkg
Linux: hiddenlayer-apim-vX.Y.Z-linux-amd64.tar.gz or hiddenlayer-apim-vX.Y.Z-linux-arm64.tar.gz
Windows: hiddenlayer-apim-vX.Y.Z-windows-amd64.zip
Bicep bundle: hiddenlayer-apim-vX.Y.Z-bicep.zip (one directory per package, each with main.bicep and main.bicepparam)

macOS .pkg installers place the binary in /usr/local/bin.

# Example for macOS Apple Silicon. Replace the version with the release you downloaded.
curl -L -O https://github.com/hiddenlayerai/hiddenlayer-azure-apim-guardrails/releases/download/v1.2.3/hiddenlayer-apim-v1.2.3-darwin-arm64.pkg
sudo installer -pkg hiddenlayer-apim-v1.2.3-darwin-arm64.pkg -target /
hiddenlayer-apim version

Install From Source

git clone https://github.com/hiddenlayerai/hiddenlayer-azure-apim-guardrails.git
cd hiddenlayer-azure-apim-guardrails/cli
make build

You can also install with Go:

go install github.com/hiddenlayerai/hiddenlayer-azure-apim-guardrails/cli@latest

Verify Azure Access

az login
az account show

If you manage multiple subscriptions, select the subscription that contains the APIM instance:

az account set --subscription "<subscription-id>"

You can also set AZURE_SUBSCRIPTION_ID in the CLI configuration.

​Prerequisites

​Azure Permissions

​Recommended Built-In Role

​Minimum Custom Role Actions

​Install From a Release

​Install From Source

​Verify Azure Access