How to use Role-Based Access Control in Azure API Management

Azure API Management relies on Azure role-based access control (Azure RBAC) to enable fine-grained access management for API Management services and entities (for example, APIs and policies). This article gives you an overview of the built-in and custom roles in API Management. For more information on access management in the Azure portal, see Get started with access management in the Azure portal.


This article uses the Azure Az PowerShell module, which is the recommended PowerShell module for interacting with Azure. To get started with the Az PowerShell module, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

Built-in roles

API Management currently provides three built-in roles and will add two more roles in the near future. These roles can be assigned at different scopes, including subscription, resource group, and individual API Management instance. For instance, if you assign the "API Management Service Reader" role to a user at the resource-group level, then the user has read access to all API Management instances inside the resource group.

The following table provides brief descriptions of the built-in roles. You can assign these roles by using the Azure portal or other tools, including Azure PowerShell, Azure CLI, and REST API. For details about how to assign built-in roles, see Assign Azure roles to manage access to your Azure subscription resources.

Role Read access[1] Write access[2] Service creation, deletion, scaling, VPN, and custom domain configuration Access to the legacy publisher portal Description
API Management Service Contributor Super user. Has full CRUD access to API Management services and entities (for example, APIs and policies). Has access to the legacy publisher portal.
API Management Service Reader Has read-only access to API Management services and entities.
API Management Service Operator Can manage API Management services, but not entities.

[1] Read access to API Management services and entities (for example, APIs and policies).

[2] Write access to API Management services and entities except the following operations: instance creation, deletion, and scaling; VPN configuration; and custom domain setup.

Custom roles

If none of the built-in roles meet your specific needs, custom roles can be created to provide more granular access management for API Management entities. For example, you can create a custom role that has read-only access to an API Management service, but only has write access to one specific API. To learn more about custom roles, see Custom roles in Azure RBAC.


To be able to see an API Management instance in the Azure portal, a custom role must include the Microsoft.ApiManagement/service/read action.

When you create a custom role, it's easier to start with one of the built-in roles. Edit the attributes to add Actions, NotActions, or AssignableScopes, and then save the changes as a new role. The following example begins with the "API Management Service Reader" role and creates a custom role called "Calculator API Editor." You can assign the custom role to a specific API. Consequently, this role only has access to that API.

$role = Get-AzRoleDefinition "API Management Service Reader Role"
$role.Id = $null
$role.Name = 'Calculator API Contributor'
$role.Description = 'Has read access to Contoso APIM instance and write access to the Calculator API.'
$role.AssignableScopes.Add('/subscriptions/<subscription ID>/resourceGroups/<resource group name>/providers/Microsoft.ApiManagement/service/<service name>/apis/<api ID>')
New-AzRoleDefinition -Role $role
New-AzRoleAssignment -ObjectId <object ID of the user account> -RoleDefinitionName 'Calculator API Contributor' -Scope '/subscriptions/<subscription ID>/resourceGroups/<resource group name>/providers/Microsoft.ApiManagement/service/<service name>/apis/<api ID>'

The Azure Resource Manager resource provider operations article contains the list of permissions that can be granted on the API Management level.

Next steps

To learn more about Role-Based Access Control in Azure, see the following articles: