Escape's Azure integration discovers APIs managed by [Azure API Management (APIM)](<https://learn.microsoft.com/en-us/azure/api-management/api-management-key-concepts>) across all subscriptions accessible by the configured service principal. Discovered APIs and their OpenAPI schemas are automatically imported as assets in Escape's ASM for continuous security testing.

## Discovered Resources

- **APIM APIs**: REST API endpoints and their OpenAPI specifications from every API Management instance the service principal can reach.

## How It Works

The integration authenticates as an [Entra ID application (service principal)](<https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals>) using a client-credentials flow, then:

1. Lists all [subscriptions](<https://learn.microsoft.com/en-us/rest/api/resources/subscriptions/list>) the principal has access to.
2. Discovers every `Microsoft.ApiManagement/service` resource via the [Azure Resource Manager](<https://learn.microsoft.com/en-us/rest/api/resources/resources/list>).
3. Enumerates [APIs](<https://learn.microsoft.com/en-us/rest/api/apimanagement/apis/list-by-service>) within each APIM instance.
4. [Exports the OpenAPI schema](<https://learn.microsoft.com/en-us/rest/api/apimanagement/api-export/get>) for each API.

## Setup

### 1\. Register an Application in Entra ID

> See [Register an application with the Microsoft identity platform](<https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app>).

### 2\. Assign Permissions

The service principal needs **read-only** access to subscriptions, resource groups, and API Management instances. Assign the following [built-in roles](<https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles>) at the scope that covers the subscriptions you want to scan (subscription or management group):

| Role | Purpose | Reference |
| --- | --- | --- |
| **Reader** | List subscriptions and discover APIM resources via Azure Resource Manager | [Reader role](<https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/general#reader>) |
| **API Management Service Reader** | List APIs and export OpenAPI schemas from APIM instances | [API Management Service Reader role](<https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/integration#api-management-service-reader-role>) |

To assign roles:

> See [Assign Azure roles using the Azure portal](<https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal>).

### 3\. Configure in Escape

Enter the three values from step 1 in Escape's Azure integration page:

| Field | Value |
| --- | --- |
| **Tenant ID** | Directory (tenant) ID of your Entra ID tenant |
| **Client ID** | Application (client) ID of the registered app |
| **Client Secret** | Secret value created for the app |

### Internal Networks

If your APIM instances are deployed in a private virtual network, you may need to configure a [Private Location](</documentation/platform/private-location/>) and whitelist the required FQDNs.