Edit

Share via

Microsoft Entra Agent ID APIs in Microsoft Graph overview (preview)

Microsoft Entra Agent ID APIs in Microsoft Graph help you create, secure, and manage AI agent identities operating in your organization. You can programmatically create agent identities, control their access to resources, and monitor their activities through a centralized platform.

In this article, you learn about the key concepts and APIs for managing agent identities in Microsoft Graph, including the components that make up an agent identity, how to apply security and governance policies to agents, and the permissions required to manage agents programmatically.

To learn more about the Microsoft Entra Agent ID, see What is Microsoft Entra Agent ID.

Building blocks of agent identities

The following core components comprise Microsoft Entra Agent ID's architecture:

Component Purpose Microsoft Graph resource
Blueprint Template defining the agent identity type, including permissions that agent identities are preauthorized to automatically inherit agentIdentityBlueprint
Blueprint principal Record of blueprint's addition to a tenant agentIdentityBlueprintPrincipal
Agent identity Primary identity for authentication agentIdentity
Agent user Optional account for scenarios that require a user account agentUser
Agent registry Centralized repository for agent management that serves as the platform for managing agent card manifests, agent instances, and agent collections.

Learn more about the agent identity architecture in the following articles:

Microsoft Entra Agent ID extends the comprehensive security and governance capabilities of Microsoft Entra to AI agents, including Conditional Access, Identity Protection, and audit logs.

Ownership and accountability

Each agent identity should have a designated party accountable for the agent's actions, access permissions, and overall security posture to ensure accountability and proper governance. Microsoft Graph APIs let you assign and manage the following metadata for agent identities, to support this principle.

Metadata Applies to
owner agentIdentityBlueprint, agentIdentityBlueprintPrincipal, agentIdentity
sponsor agentIdentityBlueprint, agentIdentityBlueprintPrincipal, agentIdentity, agentUser
manager agentUser

See Administrative relationships in Microsoft Entra Agent ID (owners, sponsors, and managers) for more information.

Conditional Access

You can programmatically apply Conditional Access policies to enforce access policies on AI agents, based on agent identity, risk and other contextual factors.

  • Use the What If evaluation API to simulate how Conditional Access policies would affect agent identities trying to access resources.
  • Use the Conditional Access policy APIs to apply or manage Conditional Access policies for AI agents accessing organizational resources. You can apply these policies based on agent risk level, or custom security attributes assigned to the agents.

Identity Protection

Microsoft Entra ID Protection continuously evaluates agent risk based on various signals and machine learning. You can use the agentRiskDetection and riskyAgent resource types to identify and manage agent risk in your organization, including dismissing or confirming detected risks. Confirmed risks can trigger automated remediation actions such as Conditional Access policy enforcement.

Audit Logs

Microsoft Entra signIn logs capture activities performed by agent identities, providing visibility into agent operations for compliance and security monitoring - from creation of agent identities to configuration changes on agents including assignments of roles and permissions.

Permissions for managing agent identities

Microsoft Graph provides granular permissions to manage agent identities and their associated components. The permissions follow the following patterns and are published in the Microsoft Graph permissions reference.

Permissions for managing the agent registry:

  • AgentCardManifest.Read*
  • AgentCollection.Read*
  • AgentInstance.Read*

Permissions for managing the agent identity blueprints and identities:

  • AgentIdentity*

Permissions for nmanaging agent users:

  • AgentIdUser.Read*

Managing Conditional Access policies, Identity Protection, and viewing audit logs for agents require the same permissions as managing these features for other identity types in Microsoft Entra. For more information, see the corresponding API articles for each feature.

Microsoft Graph permissions blocked for agents

Agent identities use the same Microsoft Graph permission model as other identities. Therefore, they can be granted delegated or application permissions to access Microsoft Graph APIs.

However, because of the autonomous nature of agents and the potential risks they pose, the following high-risk Microsoft Graph API permissions are explicitly blocked for agents to prevent misuse or unintended access to sensitive data. These permissions can't be granted to agent identities through Microsoft Graph or Microsoft Entra admin center.

Legend:

  • ❌ indicates the permission is blocked in that category
  • ➖ indicates the permission is not applicable/blocked in that category
Permission name Delegated Application
AgentIdentity.Create ➖ ❌
AgentIdentity.Create.All ➖ ❌
AgentIdentity.CreateAsManager ➖ ❌
AgentIdentityBlueprint.Create ➖ ❌
AgentIdentityBlueprint.CreateAsManager ➖ ❌
AgentIdentityBlueprint.ReadWrite.All ➖ ❌
AgentIdentityBlueprintPrincipal.Create ➖ ❌
Application.ReadWrite.All ➖ ❌
Application.ReadWrite.OwnedBy ➖ ❌
AppRoleAssignment.ReadWrite.All ➖ ❌
BitlockerKey.Read.All ➖ ❌
Calendars.Read ➖ ❌
ChannelMessage.Read.All ➖ ❌
ChannelMessage.Read.Group ➖ ❌
Chat.Read.All ➖ ❌
Chat.ReadWrite.All ➖ ❌
ConsentRequest.ReadWrite.All ➖ ❌
CustomSecAttributeAssignment.ReadWrite.All ❌ ❌
CustomSecAttributeDefinition.ReadWrite.All ❌ ❌
DelegatedPermissionGrant.ReadWrite.All ❌ ❌
Device.ReadWrite.All ➖ ❌
Device.Write.Restricted ❌ ❌
DeviceManagementConfiguration.Read.All ➖ ❌
Directory.AccessAsUser.All ❌ ➖
Directory.ReadWrite.All ❌ ❌
Directory.Write.Restricted ❌ ❌
Domain.ReadWrite.All ❌ ❌
EduRoster.ReadWrite.All ➖ ❌
EntitlementManagement.ReadWrite.All ➖ ❌
Files.Read.All ➖ ❌
Files.ReadWrite.All ➖ ❌
Group.Create ➖ ❌
Group.ReadWrite.All ❌ ❌
Group.Write.Restricted ❌ ➖
GroupMember.ReadWrite.All ❌ ❌
IdentityProvider.ReadWrite.All ➖ ❌
LifecycleManagement.ReadWrite.All ➖ ❌
Organization.ReadWrite.All ➖ ❌
Policy.ReadWrite.AuthenticationMethod ➖ ❌
Policy.ReadWrite.CrossTenantAccess ➖ ❌
Policy.ReadWrite.PermissionGrant ➖ ❌
Policy.ReadWrite.SecurityDefaults ➖ ❌
PrintJob.ReadWrite.All ➖ ❌
PrivilegedAccess.ReadWrite.AzureAD ➖ ❌
PrivilegedAccess.ReadWrite.AzureResources ➖ ❌
RoleManagement.ReadWrite.All ❌ ➖
RoleManagement.ReadWrite.Directory ❌ ❌
Sites.FullControl.All ➖ ❌
Sites.Manage.All ➖ ❌
Sites.Read.All ➖ ❌
Sites.ReadWrite.All ➖ ❌
Tasks.ReadWrite.All ➖ ❌
User-PasswordProfile.ReadWrite.All ❌ ❌
User.DeleteRestore.All ❌ ❌
User.EnableDisableAccount.All ❌ ❌
User.Invite.All ➖ ❌
User.ReadWrite.All ❌ ❌
UserAuthenticationMethod.Read.All ❌ ➖
UserAuthenticationMethod.ReadWrite.All ❌ ❌

Related content

What is Microsoft Entra Agent ID

  • Last updated on