How to use role-based access control in Azure API Management

APPLIES TO: All API Management tiers

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.

Built-in service 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.

^{[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.

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 at the scope of 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.Actions.Add('Microsoft.ApiManagement/service/apis/write')
$role.Actions.Add('Microsoft.ApiManagement/service/apis/*/write')
$role.AssignableScopes.Clear()
$role.AssignableScopes.Add('/subscriptions/<Azure subscription ID>/resourceGroups/<resource group name>/providers/Microsoft.ApiManagement/service/<APIM service instance name>/apis/<API name>')
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/<APIM service instance name>/apis/<API name>'

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:

• Get started with access management in the Azure portal
• Assign Azure roles to manage access to your Azure subscription resources
• Custom roles in Azure RBAC
• Azure Resource Manager resource provider operations