Create Delete Agent Identities
In brief
The procedure adds multi-instance guidance, clarifies identifier usage, updates Microsoft Graph paths, changes create/delete examples to POST and DELETE routes, and requires authorization on both routes.
What Entra admins need to know
Review implementations based on this procedure. Use the revised paths and configure authorization limiting access to intended administrators or owners before exposing the endpoints.
This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.
Documentation change
The comparison below shows only the changed extract. Use the full-page view for complete context.
After you create an agent identity blueprint, the next step is to create one or more agent identities that represent AI agents in your tenant. Agent identity creation is typically performed when provisioning a new AI agent.
This procedure uses a multi-instance blueprint to provision child identities. If your blueprint uses single-instance mode, follow Create a single-instance agent identity instead. Its identity shares the blueprint's client ID and doesn't use the blueprint principal provisioning path below.
You can create agent identities in two ways:
- Microsoft Entra admin center — Use the admin center wizard for quick, individual identity creation.
- An agent identity blueprint. Record the agent identity blueprint app ID from the creation process.
- A web service or application (running locally or deployed to Azure) that hosts the agent identity creation logic. This prerequisite applies only if you're creating agent identities programmatically.
Use the blueprint app ID as client_id in the token request. Save the agent identity id returned by the create call for the delete request. For identifier meanings, see Record the identifiers for your scenario.
Use the Microsoft Entra admin center
You can create an agent identity directly in the Microsoft Entra admin center by selecting an existing blueprint and assigning owners and sponsors. Always include the OData-Version header when using @odata.type.
POST https://graph.microsoft.com/beta/serviceprincipals/Microsoft.Graph.AgentIdentityservicePrincipals/microsoft.graph.agentIdentity
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>
"DownstreamApis": {
"agent-identity": {
"BaseUrl": "https://graph.microsoft.com",
"RelativePath": "/beta/serviceprincipals/Microsoft.Graph.AgentIdentityservicePrincipals/microsoft.graph.agentIdentity",
"Scopes": ["00000003-0000-0000-c000-000000000000/.default"],
"RequestAppToken": true
}
}
The code for the ASP.NET Core app (Program.cs) is the following example:example. The mutation endpoints require an authenticated caller. Configure an authorization policy that limits access to the intended administrators or owners before exposing these endpoints; the exact policy depends on your application.
using System.Text.Json.Serialization;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;
using Microsoft.IdentityModel.S2S.Extensions.AspNetCore;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
.EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddInMemoryTokenCaches(
.AddInMemoryTokenCaches();
var app = builder.Build();
app.UseHttpsRedirection();
app.UseAuthorization();
// Create an Agent identity
app.MapGet(MapPost("/create-agent-identityidentities", async (HttpContext httpContext) =>
{
try
{
{
return ex.Message;
}
}).RequireAuthorization();
app.Run();
## [Microsoft Graph API](#tab/microsoft-graph-api)
```http
DELETE https://graph.microsoft.com/beta/serviceprincipals/servicePrincipals/<agent-identity-id>/microsoft.graph.agentIdentity
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>
```csharp
// Delete an Agent identity
app.MapGet(MapDelete("/delete-agent-identityidentities/{id}", async (HttpContext httpContext, string id) =>
{
// Get the service to call the downstream API (preconfigured in the appsettings.json file)
IDownstreamApi downstreamApi = httpContext.RequestServices.GetRequiredService<IDownstreamApi>();
options.RelativePath += $"/{id}"; // Specify the ID of the agent identity to delete
});
return jsonResult;
}).RequireAuthorization();
Related content
- Plan an agent fleet on a shared runtime
- Configure inheritable permissions for blueprints
Authenticate and acquire tokens for autonomous agentsCall a custom API as an agent with ASP.NET CoreAuthenticate users and acquire tokens for interactive agentsCall a custom API as a user with ASP.NET Core- Manage owners and sponsors
- Agent identity blueprints
@@ -3,8 +3,9 @@ title: Create agent identities in Microsoft agent identity platform description: Learn how to create agent identities that represent AI agents in your tenant using Microsoft Graph APIs and various authentication libraries. titleSuffix: Microsoft Entra Agent ID ms.topic: how-to-ms.date: 04/28/2026+ms.date: 11/06/2026 ms.reviewer: dastrock+ai-usage: ai-assisted #customer-intent: As a developer, I want to create agent identities that represent my AI agents in Microsoft Entra, so that my agents can securely authenticate. ---@@ -13,6 +14,8 @@ ms.reviewer: dastrock After you create an agent identity blueprint, the next step is to create one or more [agent identities](agent-identities.md) that represent AI agents in your tenant. Agent identity creation is typically performed when provisioning a new AI agent. +This procedure uses a multi-instance blueprint to provision child identities. If your blueprint uses single-instance mode, follow [Create a single-instance agent identity](create-single-instance-agent.md#provision-the-agent-identity) instead. Its identity shares the blueprint's client ID and doesn't use the blueprint principal provisioning path below.+ You can create agent identities in two ways: - **Microsoft Entra admin center** — Use the admin center wizard for quick, individual identity creation.@@ -27,6 +30,8 @@ To create agent identities, you need: - An [agent identity blueprint](create-blueprint.md). Record the agent identity blueprint app ID from the creation process. - A web service or application (running locally or deployed to Azure) that hosts the agent identity creation logic. This prerequisite applies only if you're creating agent identities programmatically. +Use the blueprint app ID as `client_id` in the token request. Save the agent identity `id` returned by the create call for the delete request. For identifier meanings, see [Record the identifiers for your scenario](key-concepts.md#record-the-identifiers-for-your-scenario).+ ## Use the Microsoft Entra admin center You can create an agent identity directly in the Microsoft Entra admin center by selecting an existing blueprint and assigning owners and sponsors.@@ -104,7 +109,7 @@ Using the access token acquired in the previous step, you can now create agent i Always include the OData-Version header when using @odata.type. ```-POST https://graph.microsoft.com/beta/serviceprincipals/Microsoft.Graph.AgentIdentity+POST https://graph.microsoft.com/beta/servicePrincipals/microsoft.graph.agentIdentity OData-Version: 4.0 Content-Type: application/json Authorization: Bearer <token>@@ -145,7 +150,7 @@ To use *Microsoft.Identity.Web* to execute the Microsoft Graph API request to cr "DownstreamApis": { "agent-identity": { "BaseUrl": "https://graph.microsoft.com",- "RelativePath": "/beta/serviceprincipals/Microsoft.Graph.AgentIdentity",+ "RelativePath": "/beta/servicePrincipals/microsoft.graph.agentIdentity", "Scopes": ["00000003-0000-0000-c000-000000000000/.default"], "RequestAppToken": true }@@ -153,21 +158,20 @@ To use *Microsoft.Identity.Web* to execute the Microsoft Graph API request to cr } ``` -The code for the ASP.NET Core app (*Program.cs*) is the following example:+The code for the ASP.NET Core app (*Program.cs*) is the following example. The mutation endpoints require an authenticated caller. Configure an authorization policy that limits access to the intended administrators or owners before exposing these endpoints; the exact policy depends on your application. ```csharp using System.Text.Json.Serialization; using Microsoft.Identity.Abstractions; using Microsoft.Identity.Web; using Microsoft.Identity.Web.Resource;-using Microsoft.IdentityModel.S2S.Extensions.AspNetCore; var builder = WebApplication.CreateBuilder(args); // Add services to the container. builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)- .EnableTokenAcquisitionToCallDownstreamApi();-builder.Services.AddInMemoryTokenCaches();+ .EnableTokenAcquisitionToCallDownstreamApi()+ .AddInMemoryTokenCaches(); var app = builder.Build(); app.UseHttpsRedirection();@@ -175,7 +179,7 @@ app.UseAuthentication(); app.UseAuthorization(); // Create an Agent identity-app.MapGet("/create-agent-identity", async (HttpContext httpContext) =>+app.MapPost("/agent-identities", async (HttpContext httpContext) => { try {@@ -197,7 +201,7 @@ app.MapGet("/create-agent-identity", async (HttpContext httpContext) => { return ex.Message; }-});+}).RequireAuthorization(); app.Run(); @@ -233,7 +237,7 @@ When an agent is deallocated or destroyed, your service should also delete the a ## [Microsoft Graph API](#tab/microsoft-graph-api) ```http-DELETE https://graph.microsoft.com/beta/serviceprincipals/<agent-identity-id>+DELETE https://graph.microsoft.com/beta/servicePrincipals/<agent-identity-id>/microsoft.graph.agentIdentity OData-Version: 4.0 Content-Type: application/json Authorization: Bearer <token>@@ -243,7 +247,7 @@ Authorization: Bearer <token> ```csharp // Delete an Agent identity-app.MapGet("/delete-agent-identity", async (HttpContext httpContext, string id) =>+app.MapDelete("/agent-identities/{id}", async (HttpContext httpContext, string id) => { // Get the service to call the downstream API (preconfigured in the appsettings.json file) IDownstreamApi downstreamApi = httpContext.RequestServices.GetRequiredService<IDownstreamApi>();@@ -257,15 +261,16 @@ app.MapGet("/delete-agent-identity", async (HttpContext httpContext, string id) options.RelativePath += $"/{id}"; // Specify the ID of the agent identity to delete }); return jsonResult;-});+}).RequireAuthorization(); ``` --- ## Related content +- [Plan an agent fleet on a shared runtime](plan-agent-fleet.md) - [Configure inheritable permissions for blueprints](configure-inheritable-permissions-blueprints.md)-- [Authenticate and acquire tokens for autonomous agents](autonomous-agent-authentication-authorization-flow.md)-- [Authenticate users and acquire tokens for interactive agents](interactive-agent-authentication-authorization-flow.md)+- [Call a custom API as an agent with ASP.NET Core](call-api-custom.md)+- [Call a custom API as a user with ASP.NET Core](aspnet-core-call-custom-api-as-user.md) - [Manage owners and sponsors](manage-owners-sponsors-agents.md) - [Agent identity blueprints](agent-blueprint.md) 