Microsoft Entra Agent ID
Developer

Grant Microsoft Graph application permissions to an agent identity

In brief

New guidance describes three ways to grant permissions: an authorization request, the admin consent endpoint, or Microsoft Graph. Application permissions require administrator approval.

What Entra admins need to know

Administrators can enable agents to call Microsoft Graph as themselves. The guidance lists required roles, identifiers, redirect URIs, and management permissions.

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.

new file mode 100644

title: Grant Microsoft Graph application permissions to an agent identity description: Grant application permissions to an agent identity with an authorization request, the admin consent endpoint, or Microsoft Graph. titleSuffix: Microsoft Entra Agent ID ms.topic: how-to ms.date: 11/05/2026 ai-usage: ai-assisted ms.reviewer: dastrock

#customer-intent: As a developer or administrator, I want to grant Microsoft Graph application permissions to an agent identity so that it can call APIs as itself without a signed-in user.

Grant Microsoft Graph application permissions to an agent identity

Application permissions let an agent call Microsoft Graph as itself, without a signed-in user. All application permissions require administrator approval. Users can't consent to them.

You can grant application permissions to an agent identity in three ways:

MethodWho grants consentUse it when
Authorization requestAn administrator who signs in through the agent's consent flowThe agent or its setup experience prompts an administrator interactively.
Admin consent endpointAn administrator, for the organizationYou send an administrator a link to approve the agent.
Microsoft GraphAn administrator or automationYou grant permissions programmatically, such as when you provision an agent.

Prerequisites

  • An agent identity created from a blueprint. Record its client ID for methods 1 and 2, and its service principal object ID for method 3. For identifier meanings, see Record the identifiers for your scenario.
  • Global Administrator or Privileged Role Administrator role to grant admin consent.
  • For methods 1 and 2, a web redirect URI registered on the blueprint.
  • For method 3, a Microsoft Graph management client with AppRoleAssignment.ReadWrite.All and Application.Read.All. For delegated access, the signed-in administrator also needs Privileged Role Administrator to assign Microsoft Graph app roles. See the app role assignment API permissions.

Method 1: Request administrator consent with an authorization request

Direct an administrator to the authorization endpoint. Use the agent identity client ID as the OAuth client. For single-instance agents, it is shared with the blueprint; for fleets, use the selected agent's client ID, not the blueprint's. Use the role parameter to specify each required permission. The consent-only request uses response_type=none, so it records consent without returning a token.

https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize
?client_id=<agent-identity-client-id>
&response_type=none
&redirect_uri=<registered-redirect-uri>
&response_mode=query
&role=User.Read.All
&role=Mail.Read
&state=<opaque-state-value>

The administrator signs in and approves the permissions for the organization. Validate state when the browser returns to the redirect URI to prevent request forgery.

Method 2: Request administrator consent with the admin consent endpoint

Direct an administrator to the admin consent endpoint. Use the role parameter to specify each required permission:

https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent
?client_id=<agent-identity-client-id>
&role=User.Read.All
&redirect_uri=<registered-redirect-uri>
&state=<opaque-state-value>

To request multiple permissions in a single request, repeat the role parameter:

https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent
?client_id=<agent-identity-client-id>
&role=User.Read.All
&role=Mail.Read
&redirect_uri=<registered-redirect-uri>
&state=<opaque-state-value>
ParameterDescription
client_idClient ID of the agent identity. For single-instance agents, this is shared with the blueprint. For fleets, don't use the blueprint client ID.
rolePermission name to grant, such as User.Read.All. Repeat for each permission.
redirect_uriA registered redirect URI on the blueprint app registration.
stateOpaque value validated on return to prevent request forgery.

After the administrator authenticates and approves, Microsoft Entra redirects to the redirect URI. Validate state before processing the response.

Method 3: Assign application permissions with Microsoft Graph

Create an app role assignment directly on the agent identity's service principal:

Use the management client's access token, not the agent's runtime credential. Don't grant these directory-management permissions to the agent just to let it call a downstream API.

POST https://graph.microsoft.com/v1.0/servicePrincipals/<agent-identity-id>/appRoleAssignments
Content-Type: application/json
Authorization: Bearer <admin-token>

{
  "principalId": "<agent-identity-id>",
  "resourceId": "<microsoft-graph-service-principal-object-id>",
  "appRoleId": "<app-role-id>"
}
PropertyDescription
principalIdID of the agent identity.
resourceIdObject ID of the Microsoft Graph service principal in your tenant.
appRoleIdGUID of the specific application permission to grant.

Grant one permission per request.

Find the Microsoft Graph service principal object ID:

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id,displayName

Find the app role ID for a specific permission:

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=appRoles

In the response, find the entry in appRoles where value matches the permission name, such as User.Read.All. Use its id as appRoleId.

Verify the assignment

After granting permissions, verify that each app role assignment was created:

GET https://graph.microsoft.com/v1.0/servicePrincipals/<agent-identity-id>/appRoleAssignments

Each entry in the response represents one granted application permission. The agent identity can request tokens with https://graph.microsoft.com/.default to receive the granted roles in the token's roles claim.

Related content

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…