Azure Integration built-in role

API Management Service Contributor

Provides full control-plane administration for API Management services and entities, including APIs and policies. Its `Microsoft.ApiManagement/service/*` wildcard includes current secret- and key-returning operations across service and workspace entities; it has no DataActions.

Control-plane actions (7)

• Microsoft.ApiManagement/service/*
• Microsoft.Authorization/*/read
• Microsoft.Insights/alertRules/*
• Microsoft.ResourceHealth/availabilityStatuses/read
• Microsoft.Resources/deployments/*
• Microsoft.Resources/subscriptions/resourceGroups/read
• Microsoft.Support/*

Data-plane actions (0)

None — this role grants no data-plane (data access) actions.

Excluded actions (0)

None

Assignable scopes (1)

• /

Practical scope

Assign on an existing API Management service when the administrator manages only that instance. Creating a new instance or recovering a soft-deleted instance addresses a service resource under a resource group, so create-or-update authority must be inherited from the resource group or a parent scope; an assignment only on an existing instance does not authorize those parent-scope lifecycle operations.

Common use cases (3)

• Administer the configuration of an existing API Management service together with its APIs, products, policies, and related entities.
• Create or recover an API Management instance only when the principal has the required role at the containing resource group or a parent scope.
• Operate a central API platform where the same trusted team owns service configuration and API publication.

Prerequisites (3)

• The assignee must own the API platform lifecycle, including service-scale, network, custom-domain, API, policy, deletion, and portal consequences.
• For creation or soft-delete recovery, select a containing resource group and grant the required authority there or at a parent scope before the target service exists.
• Credential-bearing entities and keys in the service and its workspaces require an inventory, secret-handling process, and approved rotation procedure before assignment.

Best practices (3)

• Do not treat this broad role as the default for API authors, workspace collaborators, portal editors, or service observers; use the documented narrower roles for those duties.
• Assign directly on the API Management service and separate production changes through review and deployment controls.
• Protect and rotate any retrieved API Management secrets, subscription or user keys, tenant or gateway keys, and tool-server credentials.

Security considerations (5)

• The role can change and delete an existing service and its API entities, policies, networking, domains, and scale configuration; at resource-group or subscription scope, the same authority applies to inherited API Management services and can support service creation or recovery.
• Listing or purging soft-deleted API Management instances uses subscription-level deleted-service permissions documented separately; this role must not be described as granting that deleted-service authority.
• The service wildcard directly includes documented secret retrieval for authorization servers, backends, client applications, identity and OpenID Connect providers, named values, portal settings, properties, tenant access, tool servers, and their workspace equivalents.
• It also includes documented gateway, subscription, tenant, and user key reads or regeneration. Microsoft separately warns that entity write access can reveal credentials in write responses even when a list-secrets operation is withheld.
• The published supporting Actions also include `Microsoft.Insights/alertRules/*` and `Microsoft.Support/*`; a parent-scope assignment extends those wildcards to matching resources throughout the effective scope.

Assignment guidance

Reserve API Management Service Contributor for API platform administrators who are approved for all documented service and workspace secret/key operations. Assign it on an existing service for service-and-API administration; use a dedicated resource-group assignment only when the same principal must create or recover the instance. Use Operator for service infrastructure without API entity changes, Reader for observation, and workspace roles for delegated teams.

Related roles (3)

• API Management Service Operator Role: Manages service infrastructure without write access to API entities.
• API Management Service Reader Role: Provides read-only service and API visibility.
• API Management Developer Portal Content Editor: Limits changes to developer portal content and publication.

Editorial sources (9)

• Azure built-in roles for Integration - Azure RBAC | Microsoft Learn →

  Supports: Description, Security considerations, Related roles. Retrieved 2026-07-17.

• Understand Azure role definitions →

  Supports: Description, Security considerations. Retrieved 2026-07-17.

• Steps to assign an Azure role →

  Supports: Assignment guidance. Retrieved 2026-07-17.

• Understand scope for Azure RBAC →

  Supports: Practical scope, Assignment guidance. Retrieved 2026-07-17.

• Best practices for Azure RBAC →

  Supports: Best practices. Retrieved 2026-07-17.

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

  Supports: Description, Practical scope, Common use cases, Prerequisites, Best practices, Security considerations, Assignment guidance, Related roles. Retrieved 2026-07-17.

• Permissions for Integration - Microsoft.ApiManagement →

  Supports: Description, Prerequisites, Best practices, Security considerations, Assignment guidance. Retrieved 2026-07-17.

• Quickstart: Create a new Azure API Management instance by using the Azure portal →

  Supports: Practical scope, Common use cases, Prerequisites, Assignment guidance. Retrieved 2026-07-17.

• API Management soft-delete →

  Supports: Practical scope, Common use cases, Prerequisites, Best practices, Security considerations, Assignment guidance. Retrieved 2026-07-17.

Official Microsoft Learn documentation →