> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiddenlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#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:

```bash theme={null}
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](https://learn.microsoft.com/azure/api-management/api-management-role-based-access-control).

## 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`.

```bash theme={null}
# 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

```bash theme={null}
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:

```bash theme={null}
go install github.com/hiddenlayerai/hiddenlayer-azure-apim-guardrails/cli@latest
```

## Verify Azure Access

```bash theme={null}
az login
az account show
```

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

```bash theme={null}
az account set --subscription "<subscription-id>"
```

You can also set `AZURE_SUBSCRIPTION_ID` in the CLI configuration.