Reassign ownership of orphaned agents with the Power Platform API

Copilot Studio provides administrators with robust tools to manage bot security and compliance, including the ability to reassign ownership of orphaned agents through the Power Platform API.

Reassigning ownership of orphaned agents is part of Copilot Studio's broader security framework and works in tandem with your overall security approach in Copilot Studio.

For example, when the original owner of an agent leaves the organization or changes roles, it can lead to orphaned agents that lack proper management. This situation can disrupt business processes and create security risks, as there might not be a responsible party to manage the agent's settings and compliance requirements. Admins can use the Reassign API to reassign ownership of these orphaned agents to ensure they remain properly managed and compliant.

Agent users and makers in Copilot Studio can see agents that are reassigned. The new owner gets environment maker permissions on the bot's environment. The old owner loses access to the agent after reassignment.

Important

The powervirtualgents namespace is deprecated. Use the copilotstudio namespace in your API calls.

Prerequisites

  • You have the Bot ID and Environment ID for the target agent.
  • You must obtain a user access token issued by Microsoft Entra ID OAuth2. To obtain a token, see Authentication.
    • To reassign the owner of an agent created in Copilot Studio, the user associated with the token must have one of the following admin roles:
      • Global tenant administrator
      • AI administrator
      • Power Platform administrator
      • Environment administrator
    • To reassign the owner of an agent created in Agent Builder, the user associated with the token must have one of the following admin roles:
      • Global tenant administrator
      • AI administrator
      • Power Platform administrator
    • You must acquire the access token using the client ID of an app registration that has the CopilotStudio.AdminActions.Invoke scope granted under the Power Platform API.
  • You have the Entra User ID of the new owner to whom the agent ownership needs to be reassigned.
  • The new owner must belong to the tenant.

API operations for reassigning agent ownership

Copilot Studio supports the REST API reassign operation for reassigning orphaned agents to new owners, as part of the Power Platform API.

Note

The Reassign API doesn't support classic chatbots. The API returns 405 Method Not Allowed when you try to reassign ownership of a classic chatbot.

For more information on how and when to use the Power Platform API, see:

Reassign an agent ownership to a new owner

  • Endpoint: POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/botAdminOperations/reassign?api-version=1

  • Body: {"NewOwnerAadUserId": "EntraUserId"}

    Replace EntraUserId with the Entra User ID of the new owner.

  • Purpose: Change the owner of the agent

  • Response: No content

  • Last updated on