diff --git a/api-reference/beta/toc/toc.mapping.json b/api-reference/beta/toc/toc.mapping.json index 3e59399157d..96138a21c72 100644 --- a/api-reference/beta/toc/toc.mapping.json +++ b/api-reference/beta/toc/toc.mapping.json @@ -163,7 +163,7 @@ ] }, { - "name": "Agent user (preview)", + "name": "Agent user", "resources": [ "agentUser" ] diff --git a/api-reference/v1.0/api/agentuser-delete-manager.md b/api-reference/v1.0/api/agentuser-delete-manager.md new file mode 100644 index 00000000000..e68646f1a1b --- /dev/null +++ b/api-reference/v1.0/api/agentuser-delete-manager.md @@ -0,0 +1,81 @@ +--- +title: "Remove manager (for agentUser)" +description: "Remove an agent user's manager." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# Remove manager (for agentUser) + +Namespace: microsoft.graph + +Remove an [agentUser's](../resources/agentuser.md) manager. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | AgentIdUser.ReadWrite.IdentityParentedBy | AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | AgentIdUser.ReadWrite.IdentityParentedBy | AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +[!INCLUDE [rbac-agent-user-apis-write](../includes/rbac-for-apis/rbac-agent-user-apis-write.md)] + +## HTTP request + + +``` http +DELETE /users/{usersId}/manager/{id}/$ref +``` + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `204 No Content` response code. + +## Examples + +### Request + +The following example shows a request. + +``` http +DELETE https://graph.microsoft.com/v1.0/users/{usersId}/manager/{id}/$ref +``` + +### Response + +The following example shows the response. + +``` http +HTTP/1.1 204 No Content +``` + + diff --git a/api-reference/v1.0/api/agentuser-delete-sponsors.md b/api-reference/v1.0/api/agentuser-delete-sponsors.md new file mode 100644 index 00000000000..eb77251a3a7 --- /dev/null +++ b/api-reference/v1.0/api/agentuser-delete-sponsors.md @@ -0,0 +1,81 @@ +--- +title: "Remove sponsor (for agentUser)" +description: "Remove a user or group from the sponsors of an agent user." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# Remove sponsor (for agentUser) + +Namespace: microsoft.graph + +Remove an [agentUser's](../resources/agentuser.md) sponsor. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | AgentIdUser.ReadWrite.IdentityParentedBy | AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | AgentIdUser.ReadWrite.IdentityParentedBy | AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +[!INCLUDE [rbac-user-sponsors-apis-write](../includes/rbac-for-apis/rbac-user-sponsors-apis-write.md)] + +## HTTP request + + +``` http +DELETE /users/{usersId}/sponsors/{id}/$ref +``` + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `204 No Content` response code. + +## Examples + +### Request + +The following example shows a request. + +``` http +DELETE https://graph.microsoft.com/v1.0/users/{usersId}/sponsors/{id}/$ref +``` + +### Response + +The following example shows the response. + +``` http +HTTP/1.1 204 No Content +``` + + diff --git a/api-reference/v1.0/api/agentuser-delete.md b/api-reference/v1.0/api/agentuser-delete.md new file mode 100644 index 00000000000..89e6c554975 --- /dev/null +++ b/api-reference/v1.0/api/agentuser-delete.md @@ -0,0 +1,90 @@ +--- +title: "Delete agentUser" +description: "Delete an agentUser object." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# Delete agentUser + +Namespace: microsoft.graph + +Delete an [agentUser](../resources/agentuser.md) object. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | AgentIdUser.ReadWrite.IdentityParentedBy | AgentIdUser.ReadWrite.All, User.DeleteRestore.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | AgentIdUser.ReadWrite.IdentityParentedBy | AgentIdUser.ReadWrite.All, User.DeleteRestore.All, User.ReadWrite.All | + +> [!IMPORTANT] +> The calling user must be assigned at least one of the following [Microsoft Entra roles](/entra/identity/role-based-access-control/permissions-reference?toc=%2Fgraph%2Ftoc.json): +> - User Administrator +> - Privileged Authentication Administrator +> - Agent ID Administrator +> +> To delete users with privileged administrator roles in delegated scenarios, the app must be assigned the *Directory.AccessAsUser.All* delegated permission, and the calling user must have a higher privileged administrator role as indicated in [Who can perform sensitive actions](../resources/users.md#who-can-perform-sensitive-actions). +> +> In app-only scenarios, the *User.ReadWrite.All* application permission isn't enough privilege to delete users with privileged administrative roles. The agent must be assigned a higher privileged administrator role as indicated in [Who can perform sensitive actions](../resources/users.md#who-can-perform-sensitive-actions). + +## HTTP request + + +``` http +DELETE /users/microsoft.graph.agentUser/{userId} +``` +Note: An agent user can be deleted through the standard users' endpoint as well: DELETE /users/userId. No special odata type needs to be specified in the request. + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `204 No Content` response code. + +## Examples + +### Request + +The following example shows a request. + +``` http +DELETE https://graph.microsoft.com/v1.0/users/microsoft.graph.agentUser/ba9a3254-9f18-4209-aeb3-9e42a35b5be4 +``` + +### Response + +The following example shows the response. + +``` http +HTTP/1.1 204 No Content +``` + + diff --git a/api-reference/v1.0/api/agentuser-get.md b/api-reference/v1.0/api/agentuser-get.md new file mode 100644 index 00000000000..7b272af257a --- /dev/null +++ b/api-reference/v1.0/api/agentuser-get.md @@ -0,0 +1,238 @@ +--- +title: "Get agentUser" +description: "Read the properties and relationships of agentUser object." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# Get agentUser + +Namespace: microsoft.graph + +Read the properties and relationships of [agentUser](../resources/agentuser.md) object. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | User.ReadBasic.All | User.Read.All, AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | User.ReadBasic.All | User.Read.All, AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +#### Permissions for specific scenarios +- To read the **employeeLeaveDateTime** property: + - In delegated scenarios, the signed-in user needs at least one of the following Microsoft Entra roles: *Lifecycle Workflows Administrator* (least privilege), *Global Reader*; the app must be granted the *User-LifeCycleInfo.Read.All* delegated permission. + - In app-only scenarios with Microsoft Graph permissions, the app must be granted the *User-LifeCycleInfo.Read.All* permission. +- To read the **customSecurityAttributes** property: + - In delegated scenarios, the signed-in user must be assigned the *Attribute Assignment Administrator* role and the app granted the *CustomSecAttributeAssignment.Read.All* permission. + - In app-only scenarios with Microsoft Graph permissions, the app must be granted the *CustomSecAttributeAssignment.Read.All* permission. + +## HTTP request + + +``` http +GET /users/microsoft.graph.agentUser/{userId} +``` +Note: You can get an agent user's information through the standard users' endpoint GET /users/userId. No special odata type needs to be specified in the request. + +## Optional query parameters + +This method supports the `$select` and `$expand` OData query parameters to help customize the response. For general information, see [OData query parameters](/graph/query-parameters). + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and an [agentUser](../resources/agentuser.md) object in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +GET https://graph.microsoft.com/v1.0/users/microsoft.graph.agentUser/929393ae-1e1d-159f-0d83-29f7df42e7b9 +``` + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": { + "@odata.type": "#microsoft.graph.agentUser", + "id": "929393ae-1e1d-159f-0d83-29f7df42e7b9", + "deletedDateTime": "String (timestamp)", + "signInActivity": { + "@odata.type": "microsoft.graph.signInActivity" + }, + "cloudLicensing": { + "@odata.type": "microsoft.graph.cloudLicensing.userCloudLicensing" + }, + "accountEnabled": "Boolean", + "ageGroup": null, + "assignedLicenses": [ + { + "@odata.type": "microsoft.graph.assignedLicense" + } + ], + "assignedPlans": [ + { + "@odata.type": "microsoft.graph.assignedPlan" + } + ], + "authorizationInfo": null, + "businessPhones": [ + "String" + ], + "city": "String", + "cloudRealtimeCommunicationInfo": { + "@odata.type": "microsoft.graph.cloudRealtimeCommunicationInfo" + }, + "companyName": "String", + "consentProvidedForMinor": null, + "country": "String", + "createdDateTime": "String (timestamp)", + "creationType": "String", + "department": "String", + "displayName": "String", + "employeeHireDate": "String (timestamp)", + "employeeId": "String", + "employeeOrgData": { + "@odata.type": "microsoft.graph.employeeOrgData" + }, + "employeeType": "String", + "employeeLeaveDateTime": "String (timestamp)", + "faxNumber": "String", + "givenName": "String", + "identities": [ + { + "@odata.type": "microsoft.graph.objectIdentity" + } + ], + "imAddresses": [ + "String" + ], + "infoCatalogs": [ + "String" + ], + "isLicenseReconciliationNeeded": "Boolean", + "isManagementRestricted": "Boolean", + "isResourceAccount": "Boolean", + "jobTitle": "String", + "lastPasswordChangeDateTime": null, + "legalAgeGroupClassification": null, + "licenseAssignmentStates": [ + { + "@odata.type": "microsoft.graph.licenseAssignmentState" + } + ], + "mail": "String", + "mailNickname": "String", + "mobilePhone": "String", + "onPremisesDistinguishedName": null, + "onPremisesExtensionAttributes": null, + "onPremisesImmutableId": null, + "onPremisesLastSyncDateTime": null, + "onPremisesProvisioningErrors": null, + "onPremisesSecurityIdentifier": null, + "onPremisesSipInfo": null, + "onPremisesSyncEnabled": null, + "onPremisesDomainName": null, + "onPremisesSamAccountName": null, + "onPremisesUserPrincipalName": null, + "otherMails": [ + "String" + ], + "passwordPolicies": null, + "passwordProfile": null, + "officeLocation": "String", + "postalCode": "String", + "preferredDataLocation": "String", + "preferredLanguage": "String", + "provisionedPlans": [ + { + "@odata.type": "microsoft.graph.provisionedPlan" + } + ], + "proxyAddresses": [ + "String" + ], + "refreshTokensValidFromDateTime": "String (timestamp)", + "securityIdentifier": "String", + "serviceProvisioningErrors": [ + { + "@odata.type": "microsoft.graph.serviceProvisioningXmlError" + } + ], + "showInAddressList": "Boolean", + "signInSessionsValidFromDateTime": "String (timestamp)", + "state": "String", + "streetAddress": "String", + "surname": "String", + "usageLocation": "String", + "userPrincipalName": "String", + "externalUserState": null, + "externalUserStateChangeDateTime": null, + "userType": "String", + "identityParentId": "String", + "mailboxSettings": { + "@odata.type": "microsoft.graph.mailboxSettings" + }, + "aboutMe": "String", + "birthday": "String (timestamp)", + "interests": [ + "String" + ], + "mySite": "String", + "pastProjects": [ + "String" + ], + "preferredName": "String", + "responsibilities": [ + "String" + ], + "schools": [ + "String" + ], + "skills": [ + "String" + ] + } +} +``` + + diff --git a/api-reference/v1.0/api/agentuser-list-approleassignments.md b/api-reference/v1.0/api/agentuser-list-approleassignments.md new file mode 100644 index 00000000000..adf257fbb27 --- /dev/null +++ b/api-reference/v1.0/api/agentuser-list-approleassignments.md @@ -0,0 +1,105 @@ +--- +title: "List appRoleAssignments (for agentUser)" +description: "Retrieve the list of app role assignments granted to an agent user." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# List appRoleAssignments (for agentUser) + +Namespace: microsoft.graph + +Retrieve the list of [appRoleAssignments](../resources/approleassignment.md) granted to an [agentUser](../resources/agentuser.md). + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | AppRoleAssignment.ReadWrite.All | Directory.Read.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | Directory.Read.All | AppRoleAssignment.ReadWrite.All | + +[!INCLUDE [rbac-approleassignments-apis-read](../includes/rbac-for-apis/rbac-approleassignments-apis-read.md)] + +## HTTP request + + +``` http +GET /users/{usersId}/appRoleAssignments +``` + +## Optional query parameters + +This method supports some of the OData query parameters to help customize the response. For general information, see [OData query parameters](/graph/query-parameters). + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a collection of [appRoleAssignment](../resources/approleassignment.md) objects in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +GET https://graph.microsoft.com/v1.0/users/{usersId}/appRoleAssignments +``` + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "@odata.type": "#microsoft.graph.appRoleAssignment", + "id": "ff9f3843-845a-c408-508a-687bf19a481f", + "deletedDateTime": "String (timestamp)", + "appRoleId": "Guid", + "creationTimestamp": "String (timestamp)", + "principalDisplayName": "String", + "principalId": "Guid", + "principalType": "String", + "resourceDisplayName": "String", + "resourceId": "Guid" + } + ] +} +``` + + diff --git a/api-reference/v1.0/api/agentuser-list-directreports.md b/api-reference/v1.0/api/agentuser-list-directreports.md new file mode 100644 index 00000000000..aa815579475 --- /dev/null +++ b/api-reference/v1.0/api/agentuser-list-directreports.md @@ -0,0 +1,96 @@ +--- +title: "List directReports (for agentUser)" +description: "Get an agent user's direct reports." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# List directReports (for agentUser) + +Namespace: microsoft.graph + +Get an [agentUser's](../resources/agentuser.md) direct reports. Returns the users and contacts for whom this agent user is assigned as manager. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | User.Read.All | AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | User.Read.All | AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +## HTTP request + + +``` http +GET /users/{usersId}/directReports +``` + +## Optional query parameters + +This method supports the `$select`, `$count`, `$expand`, and `$filter` [OData query parameters](/graph/query-parameters) to help customize the response. You can use `$select` nested in the `$expand` expression. For example, `me?$expand=($select=id,displayName)`. Some queries are supported only when you use the **ConsistencyLevel** header set to `eventual` and `$count`. For more information, see [Advanced query capabilities on directory objects](/graph/aad-advanced-queries). + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a collection of [directoryObject](../resources/directoryobject.md) objects in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +GET https://graph.microsoft.com/v1.0/users/{usersId}/directReports +``` + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "@odata.type": "#microsoft.graph.directoryObject", + "id": "a6c034b8-621b-dee3-6abb-52cbce801fe9", + "deletedDateTime": "String (timestamp)" + } + ] +} +``` + + diff --git a/api-reference/v1.0/api/agentuser-list-manager.md b/api-reference/v1.0/api/agentuser-list-manager.md new file mode 100644 index 00000000000..5259f1663cb --- /dev/null +++ b/api-reference/v1.0/api/agentuser-list-manager.md @@ -0,0 +1,101 @@ +--- +title: "List manager (for agentUser)" +description: "Get the user or contact assigned as the agent user's manager." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# List manager (for agentUser) + +Namespace: microsoft.graph + +Returns the user or organizational contact assigned as the [agentUser's](../resources/agentuser.md) manager. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | User.Read.All | AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | User.Read.All | AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +## HTTP request + + +``` http +GET /users/{usersId}/manager +``` + +## Optional query parameters + +This method supports the `$select` and `$expand` [OData query parameters](/graph/query-parameters) to help customize the response. When using the `$expand` query parameter: + ++ The `n` value of `$levels` can be `max` (to return all managers) or a number between 1 and 1000. ++ When the `$levels` parameter is not specified, only the immediate manager is returned. ++ You can specify `$select` inside `$expand` to select the individual manager's properties: `$expand=manager($levels=max;$select=id,displayName)`. ++ `$levels` parameter is only supported on a single user (`/users/{id}` or `me` endpoints) and not on the entire list of users. ++ Use of `$levels` requires the **ConsistencyLevel** header set to `eventual`. For more information about the use of **ConsistencyLevel**, see [Advanced query capabilities on directory objects](/graph/aad-advanced-queries). + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a collection of [directoryObject](../resources/directoryobject.md) objects in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +GET https://graph.microsoft.com/v1.0/users/{usersId}/manager +``` + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "@odata.type": "#microsoft.graph.directoryObject", + "id": "a6c034b8-621b-dee3-6abb-52cbce801fe9" + } + ] +} +``` + + diff --git a/api-reference/v1.0/api/agentuser-list-memberof.md b/api-reference/v1.0/api/agentuser-list-memberof.md new file mode 100644 index 00000000000..422aafa77e3 --- /dev/null +++ b/api-reference/v1.0/api/agentuser-list-memberof.md @@ -0,0 +1,99 @@ +--- +title: "List agentUser direct memberships" +description: "Get groups, directory roles, and administrative units that the agent user is a direct member of. This operation isn't transitive." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# List agentUser direct memberships + +Namespace: microsoft.graph + +Get [groups](../resources/group.md), [directory roles](../resources/directoryrole.md), and [administrative units](../resources/administrativeunit.md) that the [agentUser](../resources/agentuser.md) is a direct member of. This operation isn't transitive. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | User.Read.All | AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | User.Read.All | AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +[!INCLUDE [rbac-agent-user-apis-write](../includes/rbac-for-apis/rbac-agent-user-apis-write.md)] + +## HTTP request + + +``` http +GET /users/{usersId}/memberOf +``` + +## Optional query parameters + +This method supports the [OData query parameters](/graph/query-parameters) to help customize the response, including `$search`, `$count`, and `$filter`. OData cast is also enabled; for example, you can cast to get just the **directoryRoles** the user is a member of. You can use `$search` on the **displayName** property. Items that are added or updated for this resource are specially indexed for use with the `$count` and `$search` query parameters. There can be a slight delay between when an item is added or updated and when it's available in the index. + +The use of `$filter` with this API requires the **ConsistencyLevel** header set to `eventual` and `$count`. However, in such scenarios, you can't use `$expand` in the same request as it isn't supported with advanced query parameters. For more information, see [Advanced query capabilities on directory objects](/graph/aad-advanced-queries). + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a collection of [directoryObject](../resources/directoryobject.md) objects in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +GET https://graph.microsoft.com/v1.0/users/{usersId}/memberOf +``` + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "@odata.type": "#microsoft.graph.directoryObject", + "id": "a6c034b8-621b-dee3-6abb-52cbce801fe9", + } + ] +} +``` + + diff --git a/api-reference/v1.0/api/agentuser-list-ownedobjects.md b/api-reference/v1.0/api/agentuser-list-ownedobjects.md new file mode 100644 index 00000000000..2df55be664b --- /dev/null +++ b/api-reference/v1.0/api/agentuser-list-ownedobjects.md @@ -0,0 +1,97 @@ +--- +title: "List ownedObjects (for agentUser)" +description: "Get the list of directory objects owned by the agent user." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# List ownedObjects (for agentUser) + +Namespace: microsoft.graph + +Get the list of directory objects that are owned by the [agentUser](../resources/agentuser.md). + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | User.Read.All | AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | User.Read.All | AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +[!INCLUDE [rbac-agent-user-apis-write](../includes/rbac-for-apis/rbac-agent-user-apis-write.md)] + +## HTTP request + + +``` http +GET /users/{usersId}/ownedObjects +``` + +## Optional query parameters + +This method supports some of the OData query parameters to help customize the response. For general information, see [OData query parameters](/graph/query-parameters). + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a collection of [directoryObject](../resources/directoryobject.md) objects in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +GET https://graph.microsoft.com/v1.0/users/{usersId}/ownedObjects +``` + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "@odata.type": "#microsoft.graph.directoryObject", + "id": "a6c034b8-621b-dee3-6abb-52cbce801fe9", + } + ] +} +``` + + diff --git a/api-reference/v1.0/api/agentuser-list-sponsors.md b/api-reference/v1.0/api/agentuser-list-sponsors.md new file mode 100644 index 00000000000..743b5be070a --- /dev/null +++ b/api-reference/v1.0/api/agentuser-list-sponsors.md @@ -0,0 +1,97 @@ +--- +title: "List sponsors (for agentUser)" +description: "Get an agent user's sponsors." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# List sponsors (for agentUser) + +Namespace: microsoft.graph + +Get an [agentUser's](../resources/agentuser.md) sponsors. Sponsors are users and groups that are responsible for this agent user's privileges in the tenant and for keeping the agent user's information and access up to date. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | User.Read.All | AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | User.Read.All | AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +[!INCLUDE [rbac-user-sponsors-apis-read](../includes/rbac-for-apis/rbac-user-sponsors-apis-read.md)] + +## HTTP request + + +``` http +GET /users/{usersId}/sponsors +``` + +## Optional query parameters + +This method supports the `$select` and `$expand` [OData query parameters](/graph/query-parameters) to help customize the response. You can specify `$select` inside `$expand` to select the individual sponsor's properties: `$expand=sponsors($select=id,displayName)`. + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a collection of [directoryObject](../resources/directoryobject.md) objects in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +GET https://graph.microsoft.com/v1.0/users/{usersId}/sponsors +``` + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "@odata.type": "#microsoft.graph.directoryObject", + "id": "a6c034b8-621b-dee3-6abb-52cbce801fe9", + } + ] +} +``` + + diff --git a/api-reference/v1.0/api/agentuser-list-transitivememberof.md b/api-reference/v1.0/api/agentuser-list-transitivememberof.md new file mode 100644 index 00000000000..49fc4d7c0c8 --- /dev/null +++ b/api-reference/v1.0/api/agentuser-list-transitivememberof.md @@ -0,0 +1,101 @@ +--- +title: "List an agent user's memberships (direct and transitive)" +description: "Get groups, directory roles, and administrative units that the agent user is a member of through either direct or transitive membership." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# List transitiveMemberOf + +Namespace: microsoft.graph + +Get [groups](../resources/group.md), [directory roles](../resources/directoryrole.md), and [administrative units](../resources/administrativeunit.md) that the [agentUser](../resources/agentuser.md) is a member of through either direct or transitive membership. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | User.Read.All | AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | User.Read.All | AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +[!INCLUDE [rbac-agent-user-apis-write](../includes/rbac-for-apis/rbac-agent-user-apis-write.md)] + +## HTTP request + + +``` http +GET /users/{usersId}/transitiveMemberOf +``` + +## Optional query parameters + +This method supports the `$filter`, `$count`, `$select`, `$search`, `$top` [OData query parameters](/graph/query-parameters) to help customize the response. +- OData cast is also enabled. For example, you can cast to get just the transitive membership in groups. +- `$search` is supported on the **displayName** property only. +- The default and maximum page size is 100 and 999 objects respectively. +- The use of query parameters with this API is supported only with advanced query parameters. For more information, see [Advanced query capabilities on directory objects](/graph/aad-advanced-queries). + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a collection of [directoryObject](../resources/directoryobject.md) objects in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +GET https://graph.microsoft.com/v1.0/users/{usersId}/transitiveMemberOf +``` + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "@odata.type": "#microsoft.graph.directoryObject", + "id": "a6c034b8-621b-dee3-6abb-52cbce801fe9", + } + ] +} +``` + + diff --git a/api-reference/v1.0/api/agentuser-list-transitivereports.md b/api-reference/v1.0/api/agentuser-list-transitivereports.md new file mode 100644 index 00000000000..941b441ad23 --- /dev/null +++ b/api-reference/v1.0/api/agentuser-list-transitivereports.md @@ -0,0 +1,98 @@ +--- +title: "List transitiveReports (for agentUser)" +description: "Get the transitive reports for an agent user." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# List transitiveReports (for agentUser) + +Namespace: microsoft.graph + +Get the transitive reports for an [agentUser](../resources/agentuser.md). + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | User.Read.All | AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | User.Read.All | AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +[!INCLUDE [rbac-agent-user-apis-write](../includes/rbac-for-apis/rbac-agent-user-apis-write.md)] + +## HTTP request + + +``` http +GET /users/{usersId}/transitiveReports/$count +``` + +## Optional query parameters + +This method supports some of the OData query parameters to help customize the response. For general information, see [OData query parameters](/graph/query-parameters). + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| +|ConsistencyLevel|eventual. Required.| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a collection of [directoryObject](../resources/directoryobject.md) objects in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +GET https://graph.microsoft.com/v1.0/users/{usersId}/transitiveReports/$count +``` + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "@odata.type": "#microsoft.graph.directoryObject", + "id": "a6c034b8-621b-dee3-6abb-52cbce801fe9" + } + ] +} +``` + + diff --git a/api-reference/v1.0/api/agentuser-list.md b/api-reference/v1.0/api/agentuser-list.md new file mode 100644 index 00000000000..176b5bbdd80 --- /dev/null +++ b/api-reference/v1.0/api/agentuser-list.md @@ -0,0 +1,233 @@ +--- +title: "List agentUser objects" +description: "Get a list of the agentUser objects and their properties." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# List agentUser objects + +Namespace: microsoft.graph + +Get a list of the [agentUser](../resources/agentuser.md) objects and their properties. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | User.ReadBasic.All | User.Read.All, AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | User.ReadBasic.All | User.Read.All, AgentIdUser.ReadWrite.IdentityParentedBy, AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +## HTTP request + + +``` http +GET /users/microsoft.graph.AgentUser +``` + +## Optional query parameters + +This method supports [OData query parameters](/graph/query-parameters) to help customize the response: + +- `$count`, `$expand`, `$filter`, `$orderby`, `$search`, `$select`, `$top`. `$skip` is not supported. +- **Page size limits:** The default page size is 100 objects. The maximum page size is 999 objects, except when using `$select=signInActivity` or `$filter=signInActivity`, the maximum page size is 500. +- Some queries require the **ConsistencyLevel** header set to `eventual` and `$count`. For more information, see [Advanced query capabilities on directory objects](/graph/aad-advanced-queries). + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a collection of [agentUser](../resources/agentuser.md) objects in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +GET https://graph.microsoft.com/v1.0/users/microsoft.graph.agentUser +``` + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": + { + "@odata.type": "#microsoft.graph.agentUser", + "id": "84e0b4dc-e852-29ed-1e5d-9e1f335611e8", + "deletedDateTime": "String (timestamp)", + "signInActivity": { + "@odata.type": "microsoft.graph.signInActivity" + }, + "cloudLicensing": { + "@odata.type": "microsoft.graph.cloudLicensing.userCloudLicensing" + }, + "accountEnabled": "Boolean", + "ageGroup": null, + "assignedLicenses": [ + { + "@odata.type": "microsoft.graph.assignedLicense" + } + ], + "assignedPlans": [ + { + "@odata.type": "microsoft.graph.assignedPlan" + } + ], + "authorizationInfo": null, + "businessPhones": [ + "String" + ], + "city": "String", + "cloudRealtimeCommunicationInfo": { + "@odata.type": "microsoft.graph.cloudRealtimeCommunicationInfo" + }, + "companyName": "String", + "consentProvidedForMinor": null, + "country": "String", + "createdDateTime": "String (timestamp)", + "creationType": "String", + "department": "String", + "displayName": "String", + "employeeHireDate": "String (timestamp)", + "employeeId": "String", + "employeeOrgData": { + "@odata.type": "microsoft.graph.employeeOrgData" + }, + "employeeType": "String", + "employeeLeaveDateTime": "String (timestamp)", + "faxNumber": "String", + "givenName": "String", + "identities": [ + { + "@odata.type": "microsoft.graph.objectIdentity" + } + ], + "imAddresses": [ + "String" + ], + "infoCatalogs": [ + "String" + ], + "isLicenseReconciliationNeeded": "Boolean", + "isManagementRestricted": "Boolean", + "isResourceAccount": "Boolean", + "jobTitle": "String", + "lastPasswordChangeDateTime": null, + "legalAgeGroupClassification": null, + "licenseAssignmentStates": [ + { + "@odata.type": "microsoft.graph.licenseAssignmentState" + } + ], + "mail": "String", + "mailNickname": "String", + "mobilePhone": "String", + "onPremisesDistinguishedName": null, + "onPremisesExtensionAttributes": null, + "onPremisesImmutableId": null, + "onPremisesLastSyncDateTime": null, + "onPremisesProvisioningErrors": null, + "onPremisesSecurityIdentifier": null, + "onPremisesSipInfo": null, + "onPremisesSyncEnabled": null, + "onPremisesDomainName": null, + "onPremisesSamAccountName": null, + "onPremisesUserPrincipalName": null, + "otherMails": [ + "String" + ], + "passwordPolicies": null, + "passwordProfile": null, + "officeLocation": "String", + "postalCode": "String", + "preferredDataLocation": "String", + "preferredLanguage": "String", + "provisionedPlans": [ + { + "@odata.type": "microsoft.graph.provisionedPlan" + } + ], + "proxyAddresses": [ + "String" + ], + "refreshTokensValidFromDateTime": "String (timestamp)", + "securityIdentifier": "String", + "serviceProvisioningErrors": [ + { + "@odata.type": "microsoft.graph.serviceProvisioningXmlError" + } + ], + "showInAddressList": "Boolean", + "signInSessionsValidFromDateTime": "String (timestamp)", + "state": "String", + "streetAddress": "String", + "surname": "String", + "usageLocation": "String", + "userPrincipalName": "String", + "externalUserState": null, + "externalUserStateChangeDateTime": null, + "userType": "String", + "identityParentId": "String", + "mailboxSettings": { + "@odata.type": "microsoft.graph.mailboxSettings" + }, + "aboutMe": "String", + "birthday": "String (timestamp)", + "interests": [ + "String" + ], + "mySite": "String", + "pastProjects": [ + "String" + ], + "preferredName": "String", + "responsibilities": [ + "String" + ], + "schools": [ + "String" + ], + "skills": [ + "String" + ] + } +} +``` + diff --git a/api-reference/v1.0/api/agentuser-post-approleassignments.md b/api-reference/v1.0/api/agentuser-post-approleassignments.md new file mode 100644 index 00000000000..0d459a7487e --- /dev/null +++ b/api-reference/v1.0/api/agentuser-post-approleassignments.md @@ -0,0 +1,111 @@ +--- +title: "Create appRoleAssignment (for agentUser)" +description: "Grant an app role assignment to an agent user." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# Create appRoleAssignment (for agentUser) + +Namespace: microsoft.graph + +Grant an app role assignment to an [agentUser](../resources/agentuser.md). + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | AppRoleAssignment.ReadWrite.All | Not available. | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | AppRoleAssignment.ReadWrite.All | Not available. | + +[!INCLUDE [rbac-approleassignments-apis-write](../includes/rbac-for-apis/rbac-approleassignments-apis-write.md)] + +## HTTP request + + +``` http +POST /users/{usersId}/appRoleAssignments +``` + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| +|Content-Type|application/json. Required.| + +## Request body + +In the request body, supply a JSON representation of an [appRoleAssignment](../resources/approleassignment.md) object. + +## Response + +If successful, this method returns a `201 Created` response code and an [appRoleAssignment](../resources/approleassignment.md) object in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +POST https://graph.microsoft.com/v1.0/users/{usersId}/appRoleAssignments +Content-Type: application/json + +{ + "@odata.type": "#microsoft.graph.appRoleAssignment", + "deletedDateTime": "String (timestamp)", + "appRoleId": "Guid", + "creationTimestamp": "String (timestamp)", + "principalDisplayName": "String", + "principalId": "Guid", + "principalType": "String", + "resourceDisplayName": "String", + "resourceId": "Guid" +} +``` + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 201 Created +Content-Type: application/json + +{ + "@odata.type": "#microsoft.graph.appRoleAssignment", + "id": "ff9f3843-845a-c408-508a-687bf19a481f", + "deletedDateTime": "String (timestamp)", + "appRoleId": "Guid", + "creationTimestamp": "String (timestamp)", + "principalDisplayName": "String", + "principalId": "Guid", + "principalType": "String", + "resourceDisplayName": "String", + "resourceId": "Guid" +} +``` + + diff --git a/api-reference/v1.0/api/agentuser-post-manager.md b/api-reference/v1.0/api/agentuser-post-manager.md new file mode 100644 index 00000000000..1babe3a222d --- /dev/null +++ b/api-reference/v1.0/api/agentuser-post-manager.md @@ -0,0 +1,95 @@ +--- +title: "Add manager (for agentUser)" +description: "Assign the agent user's manager." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# Add manager (for agentUser) + +Namespace: microsoft.graph + +Assign an [agentUser's](../resources/agentuser.md) manager. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | AgentIdUser.ReadWrite.IdentityParentedBy | AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | AgentIdUser.ReadWrite.IdentityParentedBy | AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +[!INCLUDE [rbac-agent-user-apis-write](../includes/rbac-for-apis/rbac-agent-user-apis-write.md)] + +## HTTP request + + +``` http +POST /users/{usersId}/manager/$ref +``` + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| +|Content-Type|application/json. Required.| + +## Request body + +In the request body, supply a JSON object and pass an `@odata.id` parameter with the read URL of the [directoryObject](../resources/directoryobject.md) or [user](../resources/user.md) object to be added. + +## Response + +If successful, this method returns a `204 No Content` response code. It doesn't return anything in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +POST https://graph.microsoft.com/v1.0/users/{usersId}/manager/$ref +Content-Type: application/json + +{ + "@odata.type": "#microsoft.graph.directoryObject" +} +``` + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 204 No Content +Content-Type: application/json + +{ + "@odata.type": "#microsoft.graph.directoryObject", + "id": "a6c034b8-621b-dee3-6abb-52cbce801fe9" +} +``` + + diff --git a/api-reference/v1.0/api/agentuser-post-sponsors.md b/api-reference/v1.0/api/agentuser-post-sponsors.md new file mode 100644 index 00000000000..9b208c28d1f --- /dev/null +++ b/api-reference/v1.0/api/agentuser-post-sponsors.md @@ -0,0 +1,96 @@ +--- +title: "Add sponsor (for agentUser)" +description: "Assign an agent user a sponsor." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# Add sponsors (for agentUser) + +Namespace: microsoft.graph + +Assign an [agentUser](../resources/agentuser.md) a sponsor. Sponsors are users and groups that are responsible for this agent user's privileges in the tenant and for keeping the agent user's information and access up to date. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | AgentIdUser.ReadWrite.IdentityParentedBy | AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | AgentIdUser.ReadWrite.IdentityParentedBy | AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +[!INCLUDE [rbac-user-sponsors-apis-write](../includes/rbac-for-apis/rbac-user-sponsors-apis-write.md)] + +## HTTP request + + +``` http +POST /users/{usersId}/sponsors/$ref +``` + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| +|Content-Type|application/json. Required.| + +## Request body + +In the request body, supply a JSON object and pass an `@odata.id` parameter with the read URL of the [user](../resources/user.md) or [group](../resources/group.md) object to be added. + +## Response + +If successful, this method returns a `204 No Content` response code. It doesn't return anything in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +POST https://graph.microsoft.com/v1.0/users/{usersId}/sponsors/$ref +Content-Type: application/json + +{ + "@odata.type": "#microsoft.graph.directoryObject" +} +``` + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 204 No Content +Content-Type: application/json + +{ + "@odata.type": "#microsoft.graph.directoryObject", + "id": "a6c034b8-621b-dee3-6abb-52cbce801fe9", + "deletedDateTime": "String (timestamp)" +} +``` + + diff --git a/api-reference/v1.0/api/agentuser-post.md b/api-reference/v1.0/api/agentuser-post.md new file mode 100644 index 00000000000..2ea821d4f40 --- /dev/null +++ b/api-reference/v1.0/api/agentuser-post.md @@ -0,0 +1,143 @@ +--- +title: "Create agentUser" +description: "Create a new agentUser." +author: "yyuank" +ms.reviewer: "iamut" +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +ms.date: 4/27/2026 +--- + +# Create agentUser + +Namespace: microsoft.graph + +Create a new [agentUser](../resources/agentuser.md) object. You can also create an agent user by using the [POST /users](../api/user-post-users.md) endpoint and specifying the `microsoft.graph.agentUser` type in the request body. + +At a minimum, you must specify the required properties. You can optionally specify any other writable properties. + +This operation returns by default only a subset of the properties for each **agentUser**. These default properties are noted in the [Properties](../resources/agentuser.md#properties) section. To get properties that are not returned by default, do a [GET operation](agentuser-get.md) and specify the properties in a `$select` OData query option. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | AgentIdUser.ReadWrite.IdentityParentedBy | AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | AgentIdUser.ReadWrite.IdentityParentedBy | AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +[!INCLUDE [rbac-agent-user-apis-write](../includes/rbac-for-apis/rbac-agent-user-apis-write.md)] + +## HTTP request + +```http +POST /users/microsoft.graph.agentUser +``` + +> [!TIP] +> You can also create agent users through the [POST /users](../api/user-post-users.md) without specifying the `microsoft.graph.agentUser` type. However, `"@odata.type": "microsoft.graph.agentUser"` must be specified in the request body together with other required properties for user creation. + +## Request headers + +| Header | Value | +|:---------------|:--------| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| +| Content-Type | application/json | + +## Request body + +In the request body, supply a JSON representation of [agentUser](../resources/agentuser.md) object. + +The following table lists the properties that are *required* when you create an **agentUser**. + +| Parameter | Type | Description| +|:---------------|:--------|:----------| +|accountEnabled |Boolean |`true` if the account is enabled; otherwise, `false`.| +|displayName |String |The name to display in the address book for the agent user.| +|mailNickname |String |The mail alias for the agent user.| +|userPrincipalName |String |The user principal name (someagent@contoso.com). It's an Internet-style login name for the agent user based on the Internet standard RFC 822. By convention, this should map to the agent user's email name. The general format is alias@domain, where domain must be present in the tenant's collection of verified domains. The verified domains for the tenant can be accessed from the **verifiedDomains** property of [organization](../resources/organization.md).
NOTE: This property cannot contain accent characters. Only the following characters are allowed `A - Z`, `a - z`, `0 - 9`, ` ' . - _ ! # ^ ~`. For the complete list of allowed characters, see [username policies](/azure/active-directory/authentication/concept-sspr-policy#userprincipalname-policies-that-apply-to-all-user-accounts).| +| identityParentId | String | The object ID of the associated [agent identity](../resources/agentidentity.md). Required.| + +Because this resource supports [extensions](/graph/extensibility-overview), you can use the `POST` operation and add custom properties with your own data to the agent user instance while creating it. + +## Response + +If successful, this method returns a `201 Created` response code and an [agentUser](../resources/agentuser.md) object in the response body. + +Attempting to create an agentUser with an **identityParentId** already linked to another agentUser returns a `400 Bad Request` error. + +## Examples + +### Request + +The following example shows a request. + + + +```http +POST https://graph.microsoft.com/v1.0/users/microsoft.graph.agentUser +Content-type: application/json + +{ + "accountEnabled": true, + "displayName": "Sales Agent", + "mailNickname": "SalesAgent", + "userPrincipalName": "salesagent@contoso.com", + "identityParentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" +} +``` + +### Response + +The following example shows the response. + +>The response object shown here might be shortened for readability. + + +```http +HTTP/1.1 201 Created +Content-type: application/json + +{ + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity", + "@odata.type": "#microsoft.graph.agentUser", + "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd", + "businessPhones": [], + "displayName": "Sales Agent", + "mail": "salesagent@contoso.com", + "mailNickname": "SalesAgent", + "userPrincipalName": "salesagent@contoso.com", + "identityParentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" +} +``` + +## Related content + +- [Add custom data to resources using extensions](/graph/extensibility-overview) +- [Add custom data to users using open extensions](/graph/extensibility-open-users) + + + + diff --git a/api-reference/v1.0/api/agentuser-update.md b/api-reference/v1.0/api/agentuser-update.md new file mode 100644 index 00000000000..b3b71a92005 --- /dev/null +++ b/api-reference/v1.0/api/agentuser-update.md @@ -0,0 +1,327 @@ +--- +title: "Update agentUser" +description: "Update the properties of an agentUser object." +author: "yyuank" +ms.reviewer: "iamut" +ms.date: 4/27/2026 +ms.localizationpriority: medium +ms.subservice: "entra-agent-id" +doc_type: apiPageType +--- + +# Update agentUser + +Namespace: microsoft.graph + +Update the properties of an [agentUser](../resources/agentuser.md) object. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +|Permission type | Least privileged permission | Higher privileged permissions | +|:--------------------|:---------------------------|:-----------------------------| +|Delegated (work or school account) | AgentIdUser.ReadWrite.IdentityParentedBy | AgentIdUser.ReadWrite.All, User.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | Not supported.| +|Application | AgentIdUser.ReadWrite.IdentityParentedBy | AgentIdUser.ReadWrite.All, User.ReadWrite.All | + +#### Permissions for specific scenarios +- Your personal Microsoft account must be tied to a Microsoft Entra tenant to update your profile with the *User.ReadWrite* delegated permission on a personal Microsoft account. +- To update the **employeeLeaveDateTime** property: + - In delegated scenarios, the admin needs the *Global Administrator* role; the app must be granted the *User.Read.All* and *User-LifeCycleInfo.ReadWrite.All* delegated permissions. + - In app-only scenarios with Microsoft Graph permissions, the app must be granted the *User.Read.All* and *User-LifeCycleInfo.ReadWrite.All* permissions. +- To update the **customSecurityAttributes** property: + - In delegated scenarios, the admin must be assigned the *Attribute Assignment Administrator* role and the app granted the *CustomSecAttributeAssignment.ReadWrite.All* permission. + - In app-only scenarios with Microsoft Graph permissions, the app must be granted the *CustomSecAttributeAssignment.ReadWrite.All* permission. +- *User-Mail.ReadWrite.All* is the least privileged permission to update the **otherMails** property. +- *User-PasswordProfile.ReadWrite.All* is the least privileged permission to update the **passwordProfile** property. +- *User-Phone.ReadWrite.All* is the least privileged permission to update the **businessPhones** and **mobilePhone** properties. +- *User.EnableDisableAccount.All* + *User.Read.All* is the least privileged combination of permissions to update the **accountEnabled** property. +- *User.ManageIdentities.All* is *required* to update the **identities** property. + +## HTTP request + + +``` http +PATCH /users/microsoft.graph.agentUser/{userId} +``` + +> [!TIP] +> You can also update agent users through the [PATCH /users/{id}](../api/user-update.md) endpoint without specifying the `microsoft.graph.agentUser` type. + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| +|Content-Type|application/json. Required.| + +## Request body + +[!INCLUDE [table-intro](../../includes/update-property-table-intro.md)] + +You must specify the **@odata.type** as `#microsoft.graph.agentUser` in the request body when updating an agentUser. + +| Property | Type |Description| +|:---------------|:--------|:----------| +|accountEnabled|Boolean| `true` if the account is enabled; otherwise, `false`. This property is required when an agent user is created.| +|assignedLicenses|[assignedLicense](../resources/assignedlicense.md) collection|The licenses that are assigned to the agent user. Not nullable.| +|businessPhones| String collection | The telephone numbers for the agent user. **NOTE:** Although this is a string collection, only one number can be set for this property.| +|city|String|The city in which the agent user is located.| +| companyName | String | The name of the company that the agent user is associated with. This property can be useful for describing the company that an external agent user comes from. The maximum length is 64 characters. | +|country|String|The country/region in which the agent user is located; for example, `US` or `UK`.| +|department|String|The name for the department in which the agent user works.| +|displayName|String|The name displayed in the address book for the agent user. This property is required when an agent user is created and it can't be cleared during updates.| +|employeeId|String|The employee identifier assigned to the agent user by the organization. The maximum length is 16 characters.| +| employeeType | String | Captures enterprise worker type. For example, `Employee`, `Contractor`, `Consultant`, or `Vendor`.| +|givenName|String|The given name (first name) of the agent user.| +|employeeHireDate|DateTimeOffset|The hire date of the agent user. The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is `2014-01-01T00:00:00Z`.| +|employeeLeaveDateTime|DateTimeOffset|The date and time when the agent user left or will leave the organization. The timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is `2014-01-01T00:00:00Z`.| +|employeeOrgData|[employeeOrgData](../resources/employeeorgdata.md) |Represents organization data (for example, division and costCenter) associated with the agent user. Include both property values when updating **employeeOrgData**; if you omit any, the system sets them to `null`.| +|jobTitle|String|The agent user's job title.| +|mail|String|The SMTP address for the agent user, for example, `salesagent@contoso.com`. Changes to this property also updates the agent user's **proxyAddresses** collection to include the value as an SMTP address. Can't be updated to `null`.| +|mailNickname|String|The mail alias for the agent user. This property must be specified when an agent user is created.| +|mobilePhone|String|The primary cellular telephone number for the agent user.| +|officeLocation|String|The office location in the agent user's place of business.| +|otherMails|String collection|A list of additional email addresses for the agent user; for example: `["salesagent@contoso.com", "agentsales@fabrikam.com"]`. To update this property, pass in all the email addresses that you want the agent user to have; otherwise, existing values get overwritten by the values you specify. Can store up to 250 values, each with a limit of 250 characters.| +|postalCode|String|The postal code for the agent user's postal address. The postal code is specific to the agent user's country/region. In the United States of America, this attribute contains the ZIP code.| +|preferredLanguage|String|The preferred language for the agent user. Should follow ISO 639-1 Code; for example, `en-US`.| +|state|String|The state or province in the agent user's address.| +|streetAddress|String|The street address of the agent user's place of business.| +|surname|String|The agent user's surname (family name or last name).| +|usageLocation|String|A two letter country code (ISO standard 3166). Required for agent users that will be assigned licenses due to legal requirement to check for availability of services in countries/regions. Examples include: `US`, `JP`, and `GB`. Not nullable.| +|userPrincipalName|String|The user principal name (UPN) of the agent user. The UPN is an Internet-style sign-in name for the agent user based on the Internet standard RFC 822. By convention, this should map to the agent user's email name. The general format is alias@domain, where domain must be present in the tenant's collection of verified domains. The verified domains for the tenant can be accessed from the **verifiedDomains** property of [organization](../resources/organization.md).
NOTE: This property can't contain accent characters. Only the following characters are allowed `A - Z`, `a - z`, `0 - 9`, ` ' . - _ ! # ^ ~`. For the complete list of allowed characters, see [username policies](/azure/active-directory/authentication/concept-sspr-policy#userprincipalname-policies-that-apply-to-all-user-accounts).| +|userType|String|A string value that can be used to classify user types in your directory, such as `Member` and `Guest`.| + +Because the **agentUser** resource supports [extensions](/graph/extensibility-overview), you can use the `PATCH` operation to add, update, or delete your own app-specific data in custom properties of an extension in an existing **agentUser** instance. + +### Manage extensions and associated data + +Use this API to manage the directory, schema, and open extensions and their data for agent users, as follows: + ++ Add, update, and store data in the extensions for an existing agent user ++ For directory and schema extensions, remove any stored data by setting the value of the custom extension property to `null`. For open extensions, use the [Delete open extension](/graph/api/opentypeextension-delete) API. + +## Response + +If successful, this method returns a `200 OK` response code and an updated [agentUser](../resources/agentuser.md) object in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +PATCH https://graph.microsoft.com/v1.0/users/microsoft.graph.agentUser/{userId} +Content-Type: application/json + +{ + "@odata.type": "#microsoft.graph.agentUser", + "accountEnabled": true, + "assignedLicenses": [ + { + "@odata.type": "microsoft.graph.assignedLicense" + } + ], + "businessPhones": [ + "+1 425 555 0109" + ], + "city": "Seattle", + "companyName": "Contoso", + "country": "United States", + "department": "Sales", + "displayName": "Sales Agent", + "employeeId": "12345", + "employeeType": "Agent", + "givenName": "Sales", + "employeeHireDate": "2024-01-15T00:00:00Z", + "employeeLeaveDateTime": null, + "employeeOrgData": { + "@odata.type": "microsoft.graph.employeeOrgData", + "division": "Sales Division", + "costCenter": "1234" + }, + "jobTitle": "Sales Agent", + "mail": "salesagent@contoso.com", + "mailNickname": "SalesAgent", + "mobilePhone": "+1 425 555 0110", + "officeLocation": "18/2111", + "otherMails": [ + "salesagent@contoso.com" + ], + "postalCode": "98052", + "preferredLanguage": "en-US", + "state": "WA", + "streetAddress": "9256 Towne Center Dr., Suite 400", + "surname": "Agent", + "usageLocation": "US", + "userPrincipalName": "salesagent@contoso.com", + "userType": "Member" +} +``` + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "@odata.type": "#microsoft.graph.agentUser", + "id": "929393ae-1e1d-159f-0d83-29f7df42e7b9", + "signInActivity": { + "@odata.type": "microsoft.graph.signInActivity" + }, + "cloudLicensing": { + "@odata.type": "microsoft.graph.cloudLicensing.userCloudLicensing" + }, + "accountEnabled": "Boolean", + "ageGroup": null, + "assignedLicenses": [ + { + "@odata.type": "microsoft.graph.assignedLicense" + } + ], + "assignedPlans": [ + { + "@odata.type": "microsoft.graph.assignedPlan" + } + ], + "authorizationInfo": null, + "businessPhones": [ + "String" + ], + "city": "String", + "cloudRealtimeCommunicationInfo": { + "@odata.type": "microsoft.graph.cloudRealtimeCommunicationInfo" + }, + "companyName": "String", + "consentProvidedForMinor": null, + "country": "String", + "createdDateTime": "String (timestamp)", + "creationType": "String", + "department": "String", + "displayName": "String", + "employeeHireDate": "String (timestamp)", + "employeeId": "String", + "employeeOrgData": { + "@odata.type": "microsoft.graph.employeeOrgData" + }, + "employeeType": "String", + "employeeLeaveDateTime": "String (timestamp)", + "faxNumber": "String", + "givenName": "String", + "identities": [ + { + "@odata.type": "microsoft.graph.objectIdentity" + } + ], + "imAddresses": [ + "String" + ], + "infoCatalogs": [ + "String" + ], + "isLicenseReconciliationNeeded": "Boolean", + "isManagementRestricted": "Boolean", + "isResourceAccount": "Boolean", + "jobTitle": "String", + "lastPasswordChangeDateTime": null, + "legalAgeGroupClassification": null, + "licenseAssignmentStates": [ + { + "@odata.type": "microsoft.graph.licenseAssignmentState" + } + ], + "mail": "String", + "mailNickname": "String", + "mobilePhone": "String", + "onPremisesDistinguishedName": null, + "onPremisesExtensionAttributes": null, + "onPremisesImmutableId": null, + "onPremisesLastSyncDateTime": null, + "onPremisesProvisioningErrors": null, + "onPremisesSecurityIdentifier": null, + "onPremisesSipInfo": null, + "onPremisesSyncEnabled": null, + "onPremisesDomainName": null, + "onPremisesSamAccountName": null, + "onPremisesUserPrincipalName": null, + "otherMails": [ + "String" + ], + "passwordPolicies": null, + "passwordProfile": null, + "officeLocation": "String", + "postalCode": "String", + "preferredDataLocation": "String", + "preferredLanguage": "String", + "provisionedPlans": [ + { + "@odata.type": "microsoft.graph.provisionedPlan" + } + ], + "proxyAddresses": [ + "String" + ], + "refreshTokensValidFromDateTime": "String (timestamp)", + "securityIdentifier": "String", + "serviceProvisioningErrors": [ + { + "@odata.type": "microsoft.graph.serviceProvisioningXmlError" + } + ], + "showInAddressList": "Boolean", + "signInSessionsValidFromDateTime": "String (timestamp)", + "state": "String", + "streetAddress": "String", + "surname": "String", + "usageLocation": "String", + "userPrincipalName": "String", + "externalUserState": null, + "externalUserStateChangeDateTime": null, + "userType": "String", + "identityParentId": "String", + "mailboxSettings": { + "@odata.type": "microsoft.graph.mailboxSettings" + }, + "aboutMe": "String", + "birthday": "String (timestamp)", + "interests": [ + "String" + ], + "mySite": "String", + "pastProjects": [ + "String" + ], + "preferredName": "String", + "responsibilities": [ + "String" + ], + "schools": [ + "String" + ], + "skills": [ + "String" + ] + } +``` + + diff --git a/api-reference/v1.0/api/directory-deleteditems-delete.md b/api-reference/v1.0/api/directory-deleteditems-delete.md index de677cd2b53..90b226c6925 100644 --- a/api-reference/v1.0/api/directory-deleteditems-delete.md +++ b/api-reference/v1.0/api/directory-deleteditems-delete.md @@ -5,18 +5,26 @@ author: "vimranga" ms.localizationpriority: medium ms.subservice: "entra-directory-management" doc_type: apiPageType -ms.date: 06/23/2025 +ms.date: 4/27/2026 --- -# Permanently delete an item (directory object) +# Permanently delete item (directory object) Namespace: microsoft.graph -Permanently delete a recently deleted [application](../resources/application.md), [group](../resources/group.md), [servicePrincipal](../resources/serviceprincipal.md), or [user](../resources/user.md) object from [deleted items](../resources/directory.md). After an item is permanently deleted, it **cannot** be restored. - Permanently delete a recently deleted directory object from [deleted items](../resources/directory.md). The following types are supported: +- [application](../resources/application.md) +- [agentIdentityBlueprint](../resources/agentidentityblueprint.md) +- [agentIdentity](../resources/agentidentity.md) +- [agentIdentityBlueprintPrincipal](../resources/agentidentityblueprintprincipal.md) +- [agentUser](../resources/agentuser.md) - [certificateBasedAuthPki](../resources/certificatebasedauthpki.md) - [certificateAuthorityDetail](../resources/certificateauthoritydetail.md) +- [externalUserProfile](../resources/externaluserprofile.md) +- [group](../resources/group.md) +- [pendingExternalUserProfile](../resources/pendingexternaluserprofile.md) +- [servicePrincipal](../resources/serviceprincipal.md) +- [user](../resources/user.md) After an item is permanently deleted, it **cannot** be restored. @@ -34,9 +42,12 @@ The following table shows the least privileged permission or permissions require | [agentIdentity](../resources/agentidentity.md) | AgentIdentity.ReadWrite.All | Not supported. | AgentIdentity.ReadWrite.All | | [agentIdentityBlueprint](../resources/agentidentityblueprint.md) | AgentIdentityBlueprint.ReadWrite.All | Not supported. | AgentIdentityBlueprint.ReadWrite.All | | [agentIdentityBlueprintPrincipal](../resources/agentidentityblueprintprincipal.md) | AgentIdentityBlueprintPrincipal.ReadWrite.All | Not supported. | AgentIdentityBlueprintPrincipal.ReadWrite.All | +| [agentUser](../resources/agentuser.md) | AgentIdUser.ReadWrite.IdentityParentedBy | Not supported. | AgentIdUser.ReadWrite.IdentityParentedBy | | [certificateBasedAuthPki](../resources/certificatebasedauthpki.md) | PublicKeyInfrastructure.Read.All | Not supported. | PublicKeyInfrastructure.Read.All | | [certificateAuthorityDetail](../resources/certificateauthoritydetail.md) | PublicKeyInfrastructure.Read.All | Not supported. | PublicKeyInfrastructure.Read.All | +| [externalUserProfile](../resources/externaluserprofile.md) | ExternalUserProfile.ReadWrite.All | Not supported | ExternalUserProfile.ReadWrite.All | | [group](../resources/group.md) | Group.ReadWrite.All | Not supported. | Not supported. | +| [pendingExternalUserProfile](../resources/pendingexternaluserprofile.md) | PendingExternalUserProfile.ReadWrite.All | Not supported | PendingExternalUserProfile.ReadWrite.All | | [servicePrincipal](../resources/serviceprincipal.md) | Application.ReadWrite.All | Not supported. | Application.ReadWrite.OwnedBy | | [user](../resources/user.md) | User.DeleteRestore.All | Not supported. | User.DeleteRestore.All | @@ -62,7 +73,6 @@ If successful, this method returns `204 No Content` response code. It doesn't re ## Example ### Request -# [HTTP](#tab/http) ```http GET /directory/deletedItems/microsoft.graph.administrativeUnit +GET /directory/deletedItems/microsoft.graph.agentIdentity +GET /directory/deletedItems/microsoft.graph.agentIdentityBlueprint +GET /directory/deletedItems/microsoft.graph.agentIdentityBlueprintPrincipal +GET /directory/deletedItems/microsoft.graph.agentUser GET /directory/deletedItems/microsoft.graph.application GET /directory/deletedItems/microsoft.graph.certificateBasedAuthPki GET /directory/deletedItems/microsoft.graph.certificateAuthorityDetail -GET /directory/deletedItems/microsoft.graph.servicePrincipal +GET /directory/deletedItems/microsoft.graph.externalUserProfile GET /directory/deletedItems/microsoft.graph.group +GET /directory/deletedItems/microsoft.graph.pendingExternalUserProfile +GET /directory/deletedItems/microsoft.graph.servicePrincipal GET /directory/deletedItems/microsoft.graph.user ``` @@ -112,7 +122,6 @@ If successful, this method returns a `200 OK` response code and collection of [d ### Example 1: Retrieve deleted groups #### Request -# [HTTP](#tab/http) +``` json +{ + "@odata.type": "#microsoft.graph.agentUser", + "id": "String (identifier)", + "deletedDateTime": "String (timestamp)", + "accountEnabled": "Boolean", + "assignedLicenses": [ + { + "@odata.type": "microsoft.graph.assignedLicense" + } + ], + "assignedPlans": [ + { + "@odata.type": "microsoft.graph.assignedPlan" + } + ], + "businessPhones": [ + "String" + ], + "city": "String", + "cloudRealtimeCommunicationInfo": { + "@odata.type": "microsoft.graph.cloudRealtimeCommunicationInfo" + }, + "companyName": "String", + "country": "String", + "countryCode": "Integer", + "createdDateTime": "String (timestamp)", + "creationType": "String", + "customSecurityAttributes": { + "@odata.type": "microsoft.graph.customSecurityAttributeValue" + }, + "department": "String", + "displayName": "String", + "employeeHireDate": "String (timestamp)", + "employeeId": "String", + "employeeOrgData": { + "@odata.type": "microsoft.graph.employeeOrgData" + }, + "employeeType": "String", + "employeeLeaveDateTime": "String (timestamp)", + "faxNumber": "String", + "givenName": "String", + "imAddresses": [ + "String" + ], + "infoCatalogs": [ + "String" + ], + "isLicenseReconciliationNeeded": "Boolean", + "isManagementRestricted": "Boolean", + "isResourceAccount": "Boolean", + "jobTitle": "String", + "licenseAssignmentStates": [ + { + "@odata.type": "microsoft.graph.licenseAssignmentState" + } + ], + "mail": "String", + "mailNickname": "String", + "mobilePhone": "String", + "otherMails": [ + "String" + ], + "officeLocation": "String", + "postalCode": "String", + "preferredDataLocation": "String", + "preferredLanguage": "String", + "provisionedPlans": [ + { + "@odata.type": "microsoft.graph.provisionedPlan" + } + ], + "proxyAddresses": [ + "String" + ], + "refreshTokensValidFromDateTime": "String (timestamp)", + "securityIdentifier": "String", + "showInAddressList": "Boolean", + "signInSessionsValidFromDateTime": "String (timestamp)", + "state": "String", + "streetAddress": "String", + "surname": "String", + "usageLocation": "String", + "userPrincipalName": "String", + "userType": "String", + "identityParentId": "String" +} +``` diff --git a/api-reference/v1.0/toc/toc.mapping.json b/api-reference/v1.0/toc/toc.mapping.json index fdd1a0b515e..7ea3bd85616 100644 --- a/api-reference/v1.0/toc/toc.mapping.json +++ b/api-reference/v1.0/toc/toc.mapping.json @@ -127,6 +127,12 @@ ] } ] + }, + { + "name": "Agent user", + "resources": [ + "agentUser" + ] } ] }, diff --git a/changelog/Microsoft.DirectoryServices.json b/changelog/Microsoft.DirectoryServices.json index 55c9de497d2..57211b54cc8 100644 --- a/changelog/Microsoft.DirectoryServices.json +++ b/changelog/Microsoft.DirectoryServices.json @@ -1,5 +1,31 @@ { "changelog": [ + { + "ChangeList": [ + { + "Id": "8191baf6-ffb1-411c-ad42-c2f78a425475", + "ApiChange": "Resource", + "ChangedApiName": "agentUser", + "ChangeType": "Addition", + "Description": "Added the [agentUser](https://learn.microsoft.com/en-us/graph/api/resources/agentUser?view=graph-rest-1.0) resource to the v1.0 endpoint.", + "Target": "agentUser" + }, + { + "Id": "8191baf6-ffb1-411c-ad42-c2f78a425475", + "ApiChange": "Method", + "ChangedApiName": "agentUser methods", + "ChangeType": "Addition", + "Description": "Added create, list, get, update, delete, and app role assignment methods for [agentUser](https://learn.microsoft.com/en-us/graph/api/resources/agentUser?view=graph-rest-1.0) in v1.0.", + "Target": "agentUser" + } + ], + "Id": "8191baf6-ffb1-411c-ad42-c2f78a425475", + "Cloud": "Prod", + "Version": "v1.0", + "CreatedDateTime": "2026-04-27T21:42:13.5895785Z", + "WorkloadArea": "Agents", + "SubArea": "Agent users" + }, { "ChangeList": [ { diff --git a/concepts/whats-new-overview.md b/concepts/whats-new-overview.md index 4254397d8b3..d66d1811d93 100644 --- a/concepts/whats-new-overview.md +++ b/concepts/whats-new-overview.md @@ -35,6 +35,10 @@ For details about previous updates to Microsoft Graph, see [Microsoft Graph what - Use the **height** and **width** parameters to [download a file in another format](/graph/api/driveitem-get-content-format) when `format=jpg`. - Use the [List activities](/graph/api/itemactivity-list) API to retrieve recent activities that took place on a [drive](/graph/api/resources/drive), [list](/graph/api/resources/list), item, or within an item hierarchy. +### Identity and access | Directory management + +- Added the [agentUser](/graph/api/resources/agentuser) resource type and related methods in v1.0 for managing agent user identities, including create, list, get, update, delete, and app role assignments. + ### Identity and access | Governance Use `approverRemove` as a new supported value for the **requestType** property of the [accessPackageAssignmentRequest](/graph/api/resources/accesspackageassignmentrequest) resource. For more information, see [accessPackageAssignmentRequest](/graph/api/resources/accesspackageassignmentrequest).