| Service | Microsoft Docs article | Related commit history on GitHub | Change details |
|---|---|---|---|
| v1.0 | Directory Deleteditems Delete | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/beta/api/directory-deleteditems-delete.md | Namespace: microsoft.graph Permanently delete an item from [deleted items](../resources/directory.md). -Currently, deleted items functionality is only supported for the [application](../resources/application.md), [group](../resources/group.md) and [user](../resources/user.md) resources. You can permanently delete an item from deleted items. But, once an item is permanently deleted, it **cannot** be restored. +Currently, deleted items functionality is only supported for the [application](../resources/application.md), [servicePrincipal](../resources/serviceprincipal.md), [group](../resources/group.md), and [user](../resources/user.md) resources. This API allows you to permanently delete an item from deleted items. But, once an item is permanently deleted, it **cannot** be restored. ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). -For applications: +### For applications and service principals: + |Permission type | Permissions (from least to most privileged) | |:--|:| For applications: The requestor needs to have one of the following roles: *Global Administrator* or *Application Administrator*. -For users: +### For users: |Permission type | Permissions (from least to most privileged) | |:--|:| For users: The signed-in user needs to have one of the following roles: *Global Administrator* or *User Administrator*. -For groups: +### For groups: |Permission type | Permissions (from least to most privileged) | |:--|:| Do not supply a request body for this method. If successful, this method returns `204 No Content` response code. It does not return anything in the response body. ## Example-##### Request +### Request # [HTTP](#tab/http) DELETE https://graph.microsoft.com/beta/directory/deleteditems/46cc6179-19d0-473 -##### Response +### Response Note: The response object shown here might be shortened for readability. <!-- { "blockType": "response", |
| v1.0 | Directory Deleteditems Get | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/beta/api/directory-deleteditems-get.md | Namespace: microsoft.graph Retrieve the properties of a recently deleted item in [deleted items](../resources/directory.md). -Currently, deleted items functionality is only supported for the [application](../resources/application.md), [group](../resources/group.md) and [user](../resources/user.md) resources. +Currently, deleted items functionality is only supported for the [application](../resources/application.md), [servicePrincipal](../resources/serviceprincipal.md), [group](../resources/group.md), and [user](../resources/user.md) resources. >**Note:** Deleted security groups are deleted permanently and can't be retrieved through this API. ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). -### For applications: +### For applications and service principals: |Permission type | Permissions (from least to most privileged) | |:--|:| GET /directory/deleteditems/{id} ``` ## Optional query parameters-This method supports the [OData Query Parameters](/graph/query-parameters) to help customize the response. +This method supports the [OData query parameters](/graph/query-parameters) to help customize the response. ## Request headers | Name |Description| |
| v1.0 | Directory Deleteditems List | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/beta/api/directory-deleteditems-list.md | Namespace: microsoft.graph Retrieve a list of recently deleted directory objects. Currently, this functionality is only supported for the [application](../resources/application.md), [group](../resources/group.md), and [user](../resources/user.md) resources. +Currently, deleted items functionality is only supported for the [application](../resources/application.md), [servicePrincipal](../resources/serviceprincipal.md), [group](../resources/group.md), and [user](../resources/user.md) resources. + >**Note:** Deleted security groups are deleted permanently and can't be retrieved through this API. ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). -### For applications: +### For applications and service principals: |Permission type | Permissions (from least to most privileged) | |:--|:| One of the following permissions is required to call this API. To learn more, in <!-- { "blockType": "ignored" } --> ```http GET /directory/deleteditems/microsoft.graph.application+GET /directory/deleteditems/microsoft.graph.servicePrincipal GET /directory/deleteditems/microsoft.graph.group GET /directory/deletedItems/microsoft.graph.user ``` -This API currently supports retrieving object types of applications (`microsoft.graph.application`), groups (`microsoft.graph.group`) or users (`microsoft.graph.user`) from deleted items. The OData cast type is a required part of the URI and calling `GET /directory/deleteditems` without a type is **not** supported. +This API currently supports retrieving object types of applications (`microsoft.graph.application`), servicePrincipals (`microsoft.graph.serviceprincipal`), groups (`microsoft.graph.group`), or users (`microsoft.graph.user`) from deleted items. The OData cast type is a required part of the URI and calling `GET /directory/deleteditems` without a type is **not** supported. ## Optional query parameters |
| v1.0 | Directory Deleteditems Restore | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/beta/api/directory-deleteditems-restore.md | Namespace: microsoft.graph Restores a recently deleted item from [deleted items](../resources/directory.md). -Currently, restore deleted items functionality is only supported for the [application](../resources/application.md), [group](../resources/group.md), and [user](../resources/user.md) resources. If an item was accidentally deleted, you can fully restore the item. This is not applicable to Security groups which are deleted permanently. +Currently, restore deleted items functionality is only supported for the [application](../resources/application.md), [servicePrincipal](../resources/serviceprincipal.md), [group](../resources/group.md), and [user](../resources/user.md) resources. If an item was accidentally deleted, you can fully restore the item. This is not applicable to Security groups, which are deleted permanently. A recently deleted item will remain available for up to 30 days. After 30 days, the item is permanently deleted. ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). -### For applications: +### For applications and service principals: |Permission type | Permissions (from least to most privileged) | |:--|:| |Delegated (work or school account) | Application.ReadWrite.All | |Delegated (personal Microsoft account) | Not supported. |-|Application | Application.ReadWrite.All, Application.ReadWrite.OwnedBy | +|Application | Application.ReadWrite.OwnedBy, Application.ReadWrite.All | ### For users: |
| v1.0 | Directorysetting Delete | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/beta/api/directorysetting-delete.md | Delete a directory setting. ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). +### For all settings except the Consent Policy Settings object + |Permission type | Permissions (from least to most privileged) | |:--|:| |Delegated (work or school account) | Directory.ReadWrite.All | |Delegated (personal Microsoft account) | Not supported. | |Application | Directory.ReadWrite.All | +### For the Consent Policy Settings object ++The following permissions are required to update the "Consent Policy Settings" **directorySetting** object. ++|Permission type | Permissions (from least to most privileged) | +|:--|:| +|Delegated (work or school account) | Policy.ReadWrite.Authorization | +|Delegated (personal Microsoft account) | Not supported. | +|Application | Policy.ReadWrite.Authorization | + ## HTTP request <!-- { "blockType": "ignored" } --> Delete a tenant-wide setting. |
| v1.0 | Directorysetting Update | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/beta/api/directorysetting-update.md | Update the properties of a specific directory setting object. ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). +### For all settings except the Consent Policy Settings object + |Permission type | Permissions (from least to most privileged) | |:--|:| |Delegated (work or school account) | Directory.ReadWrite.All | |Delegated (personal Microsoft account) | Not supported. | |Application | Directory.ReadWrite.All | +### For the Consent Policy Settings object ++The following permissions are required to update the "Consent Policy Settings" **directorySetting** object. ++|Permission type | Permissions (from least to most privileged) | +|:--|:| +|Delegated (work or school account) | Policy.ReadWrite.Authorization | +|Delegated (personal Microsoft account) | Not supported. | +|Application | Policy.ReadWrite.Authorization | + ## HTTP request <!-- { "blockType": "ignored" } --> |
| v1.0 | Plannerbucket Delete | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/beta/api/plannerbucket-delete.md | Title: "Delete plannerBucket" -description: "Delete **plannerBucket**." +description: "Delete plannerBucket." ms.localizationpriority: medium ms.prod: "planner" Namespace: microsoft.graph [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] Delete **plannerBucket**.+ ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). One of the following permissions is required to call this API. To learn more, in ```http DELETE /planner/buckets/{id} ```+ ## Request headers | Name | Description| |:|:-| Do not supply a request body for this method. ## Response -If successful, this method returns `204 No Content` response code. It does not return anything in the response body. +If successful, this method returns a `204 No Content` response code. It does not return anything in the response body. This method can return any of the [HTTP status codes](/graph/errors). The most common errors that apps should handle for this method are the 400, 403, 404, 409, and 412 responses. For more information about these errors, see [Common Planner error conditions](../resources/planner-overview.md#common-planner-error-conditions). ## Example-##### Request -Here is an example of the request. +### Request +The following is an example of a request. # [HTTP](#tab/http) <!-- { If-Match: W/"JzEtVGFzayAgQEBAQEBAQEBAQEBAQEBAWCc=" -##### Response -Here is an example of the response. Note: The response object shown here might be shortened for readability. +### Response +The following is an example of the response. <!-- { "blockType": "response", "truncated": true |
| v1.0 | User List Transitivememberof | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/beta/api/user-list-transitivememberof.md | Get [groups](../resources/group.md), [directory roles](../resources/directoryrol One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). -| Permission type | Permissions (from least to most privileged) | -| :- | : | -| Delegated (work or school account) | Directory.Read.All, Directory.ReadWrite.All | -| Delegated (personal Microsoft account) | Not supported. | -| Application | Directory.Read.All, Directory.ReadWrite.All | +| Permission type | Permissions (from least to most privileged) | +| :- | : | +| Delegated (work or school account) | User.Read, GroupMember.Read.All, Directory.Read.All, Directory.ReadWrite.All | +| Delegated (personal Microsoft account) | Not supported. | +| Application | Directory.Read.All, Directory.ReadWrite.All | ## HTTP request |
| v1.0 | User Update | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/beta/api/user-update.md | In the request body, supply the values for relevant fields that should be update |onPremisesImmutableId|String|This property is used to associate an on-premises Active Directory user account to their Azure AD user object. This property must be specified when creating a new user account in the Graph if you are using a federated domain for the userΓÇÖs **userPrincipalName** (UPN) property. **Important:** The **$** and **_** characters cannot be used when specifying this property. | |otherMails|String collection|A list of additional email addresses for the user; for example: `["bob@contoso.com", "Robert@fabrikam.com"]`.| |passwordPolicies|String|Specifies password policies for the user. This value is an enumeration with one possible value being `DisableStrongPassword`, which allows weaker passwords than the default policy to be specified. `DisablePasswordExpiration` can also be specified. The two may be specified together; for example: `DisablePasswordExpiration, DisableStrongPassword`.|-|passwordProfile|[PasswordProfile](../resources/passwordprofile.md)|Specifies the password profile for the user. The profile contains the userΓÇÖs password. This property is required when a user is created. The password in the profile must satisfy minimum requirements as specified by the **passwordPolicies** property. By default, a strong password is required. <br><br>The calling user must be assigned the *Directory.AccessAsUser.All* delegated permission to update this property. This property cannot be updated with only application permissions.| +|passwordProfile|[PasswordProfile](../resources/passwordprofile.md)|Specifies the password profile for the user. The profile contains the userΓÇÖs password. This property is required when a user is created. The password in the profile must satisfy minimum requirements as specified by the **passwordPolicies** property. By default, a strong password is required. <br><br> In delegated access, the calling app must be assigned the *Directory.AccessAsUser.All* delegated permission on behalf of the signed-in user. In application-only access, the calling app must be assigned the *User.ReadWrite.All* application permission and at least the *User Administrator* [Azure AD role](/azure/active-directory/roles/permissions-reference).| |pastProjects|String collection|A list for the user to enumerate their past projects.| |postalCode|String|The postal code for the user's postal address. The postal code is specific to the user's country/region. In the United States of America, this attribute contains the ZIP code.| |preferredLanguage|String|The preferred language for the user. Should follow ISO 639-1 Code; for example `en-US`.| Because the **user** resource supports [extensions](/graph/extensibility-overvie add, update, or delete your own app-specific data in custom properties of an extension in an existing **user** instance. > [!NOTE] -> - The following properties cannot be updated by an app with only application permissions: **aboutMe**, **birthday**, **employeeHireDate**, **interests**, **mySite**, **pastProjects**, **preferredName**, **responsibilities**, **schools**, and **skills**. -> - To update the following properties, you must specify them in their own PATCH request, without including the other properties listed in the table above: **aboutMe**, **birthday**, **interests**, **mySite**, **pastProjects**, **preferredName**, **responsibilities**, **schools**, and **skills**. +> - The following properties cannot be updated by an app with only application permissions: **aboutMe**, **birthday**, **employeeHireDate**, **interests**, **mySite**, **pastProjects**, **responsibilities**, **schools**, and **skills**. +> - To update the following properties, you must specify them in their own PATCH request, without including the other properties listed in the table above: **aboutMe**, **birthday**, **interests**, **mySite**, **pastProjects**, **responsibilities**, **schools**, and **skills**. ### Manage extensions and associated data HTTP/1.1 204 No Content ### Example 3: Update the passwordProfile of a user to reset their password -The following example shows a request that resets the password of another user. The calling user must be assigned the *Directory.AccessAsUser.All* delegated permission to update this property. +The following example shows a request that resets the password of another user. #### Request |
| v1.0 | Externalconnectors Displaytemplate | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/beta/resources/externalconnectors-displaytemplate.md | Defines the appearance of the content and the conditions that dictate when the t ## Properties |Property|Type|Description| |:|:|:|-|id|String|The text identifier for the display template; for example, `contosoTickets`.| +|id|String|The text identifier for the display template; for example, `contosoTickets`. Maximum 16 characters. Only alphanumeric characters allowed. | |layout|[microsoft.graph.Json](../resources/intune-mam-json.md)|The definition of the content's appearance, represented by an [Adaptive Card](/adaptive-cards/authoring-cards/getting-started), which is a JSON-serialized card object model.|-|priority|Int32|Defines the priority of a display template. A display template with priority 1 is evaluated before a template with priority 4. Gaps in priority values are supported.| +|priority|Int32|Defines the priority of a display template. A display template with priority 1 is evaluated before a template with priority 4. Gaps in priority values are supported. Must be positive value.| |rules|[microsoft.graph.externalConnectors.propertyRule](../resources/externalconnectors-propertyrule.md) collection|Specifies additional rules for selecting this display template based on the item schema. Optional.| ## Relationships |
| v1.0 | Externalconnectors Searchsettings | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/beta/resources/externalconnectors-searchsettings.md | Collects all configurable settings related to search over connector content. ## Properties |Property|Type|Description| |:|:|:|-|searchResultTemplates|[microsoft.graph.externalConnectors.displayTemplate](../resources/externalconnectors-displaytemplate.md) collection|Enables the developer to define the appearance of the content and configure conditions that dictate when the template should be displayed.| +|searchResultTemplates|[microsoft.graph.externalConnectors.displayTemplate](../resources/externalconnectors-displaytemplate.md) collection|Enables the developer to define the appearance of the content and configure conditions that dictate when the template should be displayed. Maximum of 2 search result templates per connection.| ## Relationships None. |
| v1.0 | Serviceprincipal | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/beta/resources/serviceprincipal.md | This resource supports using [delta query](/graph/delta-query-overview) to track |[Get servicePrincipal](../api/serviceprincipal-get.md) | [servicePrincipal](serviceprincipal.md) |Read properties and relationships of servicePrincipal object.| |[Update servicePrincipal](../api/serviceprincipal-update.md) | [servicePrincipal](serviceprincipal.md) |Update servicePrincipal object. | |[Delete servicePrincipal](../api/serviceprincipal-delete.md) | None |Delete servicePrincipal object.|+|[List deleted servicePrincipals](../api/directory-deleteditems-list.md) | [directoryObject](directoryobject.md) collection | Retrieve a list of recently deleted servicePrincipal objects. | +|[Get deleted servicePrincipal](../api/directory-deleteditems-get.md) | [directoryObject](directoryobject.md) | Retrieve the properties of a recently deleted servicePrincipal object. | +|[Permanently delete servicePrincipal](../api/directory-deleteditems-delete.md) | None | Permanently delete a servicePrincipal object. | +|[Restore deleted servicePrincipal](../api/directory-deleteditems-restore.md) | [directoryObject](directoryobject.md) | Restore a recently deleted servicePrincipal object. | |[List createdObjects](../api/serviceprincipal-list-createdobjects.md) |[directoryObject](directoryobject.md) collection| Get a createdObject object collection.| |[List ownedObjects](../api/serviceprincipal-list-ownedobjects.md) |[directoryObject](directoryobject.md) collection| Get an ownedObject object collection.| |[delta](../api/serviceprincipal-delta.md)|servicePrincipal collection| Get incremental changes for service principals. | |
| v1.0 | User | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/beta/resources/user.md | This resource supports: | onPremisesProvisioningErrors | [onPremisesProvisioningError](onpremisesprovisioningerror.md) collection | Errors when using Microsoft synchronization product during provisioning. <br> Supports `$filter` (`eq`, `not`, `ge`, `le`).| | onPremisesSamAccountName | String | Contains the on-premises `sAMAccountName` synchronized from the on-premises directory. The property is only populated for customers who are synchronizing their on-premises directory to Azure Active Directory via Azure AD Connect. Read-only.<br><br> Supports `$filter` (`eq`, `ne`, `not`, `ge`, `le`, `in`, `startsWith`).| | onPremisesSecurityIdentifier | String | Contains the on-premises security identifier (SID) for the user that was synchronized from on-premises to the cloud. Read-only. Supports `$filter` (`eq` including on `null` values). |-| onPremisesSyncEnabled | Boolean | `true` if this object is synced from an on-premises directory; `false` if this object was originally synced from an on-premises directory but is no longer synced; `null` if this object has never been synced from an on-premises directory (default). Read-only. <br><br>Supports `$filter` (`eq`, `ne`, `not`, `in`, and `eq` on `null` values). | +| onPremisesSyncEnabled | Boolean | `true` if this user object is currently being synced from an on-premises Active Directory (AD); otherwise the user isn't being synced and can be managed in Azure Active Directory (Azure AD). Read-only. <br><br>Supports `$filter` (`eq`, `ne`, `not`, `in`, and `eq` on `null` values). | | onPremisesUserPrincipalName | String | Contains the on-premises `userPrincipalName` synchronized from the on-premises directory. The property is only populated for customers who are synchronizing their on-premises directory to Azure Active Directory via Azure AD Connect. Read-only. <br><br>Supports `$filter` (`eq`, `ne`, `not`, `ge`, `le`, `in`, `startsWith`). | | otherMails | String collection | A list of additional email addresses for the user; for example: `["bob@contoso.com", "Robert@fabrikam.com"]`.<br>NOTE: This property cannot contain accent characters.<br><br>Supports `$filter` (`eq`, `not`, `ge`, `le`, `in`, `startsWith`, `endsWith`, and counting empty collections). | | passwordPolicies | String | Specifies password policies for the user. This value is an enumeration with one possible value being `DisableStrongPassword`, which allows weaker passwords than the default policy to be specified. `DisablePasswordExpiration` can also be specified. The two may be specified together; for example: `DisablePasswordExpiration, DisableStrongPassword`. For more information on the default password policies, see [Azure AD pasword policies](/azure/active-directory/authentication/concept-sspr-policy#password-policies-that-only-apply-to-cloud-user-accounts). <br><br>Supports `$filter` (`ne`, `not`, and `eq` on `null` values).| This resource supports: | postalCode | String | The postal code for the user's postal address. The postal code is specific to the user's country/region. In the United States of America, this attribute contains the ZIP code. Maximum length is 40 characters. <br><br>Supports `$filter` (`eq`, `ne`, `not`, `ge`, `le`, `in`, `startsWith`, and `eq` on `null` values).| | preferredDataLocation | String | The preferred data location for the user. For more information, see [OneDrive Online Multi-Geo](/sharepoint/dev/solution-guidance/multigeo-introduction).| | preferredLanguage | String | The preferred language for the user. Should follow ISO 639-1 Code; for example `en-US`. <br><br>Supports `$filter` (`eq`, `ne`, `not`, `ge`, `le`, `in`, `startsWith`, and `eq` on `null` values). |-| preferredName | String | The preferred name for the user. <br><br>Returned only on `$select`. | +| preferredName | String | The preferred name for the user. **Not Supported. This attribute returns an empty string.**<br><br>Returned only on `$select`. | | provisionedPlans | [provisionedPlan](provisionedplan.md) collection | The plans that are provisioned for the user. Read-only. Not nullable. Supports `$filter` (`eq`, `not`, `ge`, `le`).| | proxyAddresses | String collection | For example: `["SMTP: bob@contoso.com", "smtp: bob@sales.contoso.com"]`. Changes to the **mail** property will also update this collection to include the value as an SMTP address. For more information, see [mail and proxyAddresses properties](#mail-and-proxyaddresses-properties). The proxy address prefixed with `SMTP` (capitalized) is the primary proxy address while those prefixed with `smtp` are the secondary proxy addresses. For Azure AD B2C accounts, this property has a limit of ten unique addresses. Read-only in Microsoft Graph; you can update this property only through the [Microsoft 365 admin center](/exchange/recipients-in-exchange-online/manage-user-mailboxes/add-or-remove-email-addresses). Not nullable. <br><br>Supports `$filter` (`eq`, `not`, `ge`, `le`, `startsWith`, `endsWith`, and counting empty collections). | | refreshTokensValidFromDateTime | DateTimeOffset | Any refresh tokens or sessions tokens (session cookies) issued before this time are invalid, and applications will get an error when using an invalid refresh or sessions token to acquire a delegated access token (to access APIs such as Microsoft Graph). If this happens, the application will need to acquire a new refresh token by making a request to the authorize endpoint. Read-only. Use [invalidateAllRefreshTokens](../api/user-invalidateallrefreshtokens.md) to reset.| |
| v1.0 | Directory Deleteditems Delete | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/v1.0/api/directory-deleteditems-delete.md | Namespace: microsoft.graph Permanently deletes an item from [deleted items](../resources/directory.md). -Currently, deleted items functionality is only supported for the [application](../resources/application.md), [group](../resources/group.md) and [user](../resources/user.md) resources. You can permanently delete an item from deleted items. But, once an item is permanently deleted, it **cannot** be restored. +Currently, deleted items functionality is only supported for the [application](../resources/application.md), [servicePrincipal](../resources/serviceprincipal.md), [group](../resources/group.md) and [user](../resources/user.md) resources. You can permanently delete an item from deleted items. But, once an item is permanently deleted, it **cannot** be restored. ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). -For applications: +### For applications and service principals: + |Permission type | Permissions (from least to most privileged) | |:--|:| For applications: The requestor needs to have one of the following roles: *Global Administrator* or *Application Administrator*. -For users: +### For users: |Permission type | Permissions (from least to most privileged) | |:--|:| For users: The signed-in user needs to have one of the following roles: *Global Administrator* or *User Administrator*. -For groups: +### For groups: |Permission type | Permissions (from least to most privileged) | |:--|:| |
| v1.0 | Directory Deleteditems Get | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/v1.0/api/directory-deleteditems-get.md | Namespace: microsoft.graph Retrieve the properties of a recently deleted item in [deleted items](../resources/directory.md). -Currently, deleted items functionality is only supported for the [application](../resources/application.md), [group](../resources/group.md) and [user](../resources/user.md) resources. +Currently, deleted items functionality is only supported for the [application](../resources/application.md), [servicePrincipal](../resources/serviceprincipal.md), [group](../resources/group.md), and [user](../resources/user.md) resources. >**Note:** Deleted security groups are deleted permanently and can't be retrieved through this API. ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). -### For applications: +### For applications and service principals: |Permission type | Permissions (from least to most privileged) | |:--|:| |
| v1.0 | Directory Deleteditems List | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/v1.0/api/directory-deleteditems-list.md | Namespace: microsoft.graph Retrieve a list of recently deleted directory objects. Currently, this functionality is only supported for the [application](../resources/application.md), [group](../resources/group.md), and [user](../resources/user.md) resources. +Currently, deleted items functionality is only supported for the [application](../resources/application.md), [servicePrincipal](../resources/serviceprincipal.md), [group](../resources/group.md), and [user](../resources/user.md) resources. + >**Note:** Deleted security groups are deleted permanently and can't be retrieved through this API. ## Permissions Retrieve a list of recently deleted directory objects. Currently, this functiona One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). -### For applications: +### For applications and service principals: |Permission type | Permissions (from least to most privileged) | |:--|:| One of the following permissions is required to call this API. To learn more, in <!-- { "blockType": "ignored" } --> ```http GET /directory/deleteditems/microsoft.graph.application+GET /directory/deleteditems/microsoft.graph.servicePrincipal GET /directory/deletedItems/microsoft.graph.group GET /directory/deletedItems/microsoft.graph.user GET /directory/deletedItems/microsoft.graph.device ``` -This API currently supports retrieving object types of applications (`microsoft.graph.application`), groups (`microsoft.graph.group`) or users (`microsoft.graph.user`) from deleted items. The OData cast type is a required part of the URI and calling `GET /directory/deleteditems` without a type is **not** supported. +This API currently supports retrieving object types of applications (`microsoft.graph.application`), servicePrincipals (`microsoft.graph.serviceprincipal`), groups (`microsoft.graph.group`), or users (`microsoft.graph.user`) from deleted items. The OData cast type is a required part of the URI and calling `GET /directory/deleteditems` without a type is **not** supported. ## Optional query parameters |
| v1.0 | Directory Deleteditems Restore | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/v1.0/api/directory-deleteditems-restore.md | Namespace: microsoft.graph Restores a recently deleted item from [deleted items](../resources/directory.md). -Currently, restore deleted items functionality is only supported for the [application](../resources/application.md), [group](../resources/group.md) and [user](../resources/user.md) resources. If an item was accidentally deleted, you can fully restore the item. This is not applicable to Security groups, which are deleted permanently. +Currently, restore deleted items functionality is only supported for the [application](../resources/application.md), [servicePrincipal](../resources/serviceprincipal.md), [group](../resources/group.md), and [user](../resources/user.md) resources. If an item was accidentally deleted, you can fully restore the item. This is not applicable to Security groups, which are deleted permanently. A recently deleted item will remain available for up to 30 days. After 30 days, the item is permanently deleted. ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). -### For applications: +### For applications and service principals: |Permission type | Permissions (from least to most privileged) | |:--|:| |
| v1.0 | Groupsetting Delete | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/v1.0/api/groupsetting-delete.md | Delete a tenant-level or group-specific [groupSetting](../resources/groupsetting One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). -| Permission type | Permissions (from least to most privileged) | -| :- | : | -| Delegated (work or school account) | Directory.ReadWrite.All | -| Delegated (personal Microsoft account) | Not supported. | -| Application | Directory.ReadWrite.All | +### For all settings except the Consent Policy Settings object ++|Permission type | Permissions (from least to most privileged) | +|:--|:| +|Delegated (work or school account) | Directory.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | +|Application | Directory.ReadWrite.All | ++### For the Consent Policy Settings object ++The following permissions are required to update the "Consent Policy Settings" **directorySetting** object. ++|Permission type | Permissions (from least to most privileged) | +|:--|:| +|Delegated (work or school account) | Policy.ReadWrite.Authorization | +|Delegated (personal Microsoft account) | Not supported. | +|Application | Policy.ReadWrite.Authorization | ## HTTP request |
| v1.0 | Groupsetting Update | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/v1.0/api/groupsetting-update.md | Update the properties of a [groupSetting](../resources/groupsetting.md) object f One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). -| Permission type | Permissions (from least to most privileged) | -| :- | : | -| Delegated (work or school account) | Directory.ReadWrite.All | -| Delegated (personal Microsoft account) | Not supported. | -| Application | Directory.ReadWrite.All | +### For all settings except the Consent Policy Settings object ++|Permission type | Permissions (from least to most privileged) | +|:--|:| +|Delegated (work or school account) | Directory.ReadWrite.All | +|Delegated (personal Microsoft account) | Not supported. | +|Application | Directory.ReadWrite.All | ++### For the Consent Policy Settings object ++The following permissions are required to update the "Consent Policy Settings" **directorySetting** object. ++|Permission type | Permissions (from least to most privileged) | +|:--|:| +|Delegated (work or school account) | Policy.ReadWrite.Authorization | +|Delegated (personal Microsoft account) | Not supported. | +|Application | Policy.ReadWrite.Authorization | ## HTTP request |
| v1.0 | Plannerbucket Delete | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/v1.0/api/plannerbucket-delete.md | Title: "Delete plannerBucket" -description: "Delete **plannerBucket**." +description: "Delete plannerBucket." ms.localizationpriority: medium ms.prod: "planner" doc_type: apiPageType Namespace: microsoft.graph Delete **plannerBucket**.+ ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). One of the following permissions is required to call this API. To learn more, in ```http DELETE /planner/buckets/{id} ```+ ## Request headers | Name | Description| |:|:-| Do not supply a request body for this method. ## Response -If successful, this method returns `204 No Content` response code. It does not return anything in the response body. +If successful, this method returns a `204 No Content` response code. It does not return anything in the response body. This method can return any of the [HTTP status codes](/graph/errors). The most common errors that apps should handle for this method are the 400, 403, 404, 409, and 412 responses. For more information about these errors, see [Common Planner error conditions](../resources/planner-overview.md#common-planner-error-conditions). ## Example-##### Request -Here is an example of the request. +### Request +The following is an example of a request. # [HTTP](#tab/http) <!-- { If-Match: W/"JzEtVGFzayAgQEBAQEBAQEBAQEBAQEBAWCc=" -##### Response -Here is an example of the response. Note: The response object shown here might be shortened for readability. +### Response +The following is an example of the response. <!-- { "blockType": "response", "truncated": true |
| v1.0 | User List Transitivememberof | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/v1.0/api/user-list-transitivememberof.md | Get [groups](../resources/group.md), [directory roles](../resources/directoryrol One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). -| Permission type | Permissions (from least to most privileged) | -| :- | : | -| Delegated (work or school account) | Directory.Read.All, Directory.ReadWrite.All | -| Delegated (personal Microsoft account) | Not supported. | -| Application | Directory.Read.All, Directory.ReadWrite.All | +| Permission type | Permissions (from least to most privileged) | +| :- | : | +| Delegated (work or school account) | User.Read, GroupMember.Read.All, Directory.Read.All, Directory.ReadWrite.All | +| Delegated (personal Microsoft account) | Not supported. | +| Application | Directory.Read.All, Directory.ReadWrite.All | [!INCLUDE [limited-info](../../includes/limited-info.md)] |
| v1.0 | User Update | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/v1.0/api/user-update.md | In the request body, supply the values for relevant fields that should be update |onPremisesImmutableId|String|This property is used to associate an on-premises Active Directory user account to their Azure AD user object. This property must be specified when creating a new user account in the Graph if you are using a federated domain for the userΓÇÖs **userPrincipalName** (UPN) property. **Important:** The **$** and **_** characters cannot be used when specifying this property. | |otherMails|String collection |A list of additional email addresses for the user; for example: `["bob@contoso.com", "Robert@fabrikam.com"]`.| |passwordPolicies|String|Specifies password policies for the user. This value is an enumeration with one possible value being `DisableStrongPassword`, which allows weaker passwords than the default policy to be specified. `DisablePasswordExpiration` can also be specified. The two may be specified together; for example: `DisablePasswordExpiration, DisableStrongPassword`.|-|passwordProfile|[PasswordProfile](../resources/passwordprofile.md)|Specifies the password profile for the user. The profile contains the userΓÇÖs password. This property is required when a user is created. The password in the profile must satisfy minimum requirements as specified by the **passwordPolicies** property. By default, a strong password is required. This cannot be used for federated users. <br><br> The calling user must be assigned the *Directory.AccessAsUser.All* delegated permission to update this property. This property cannot be updated with only application permissions.| +|passwordProfile|[PasswordProfile](../resources/passwordprofile.md)|Specifies the password profile for the user. The profile contains the userΓÇÖs password. This property is required when a user is created. The password in the profile must satisfy minimum requirements as specified by the **passwordPolicies** property. By default, a strong password is required. This cannot be used for federated users. <br><br> In delegated access, the calling app must be assigned the *Directory.AccessAsUser.All* delegated permission on behalf of the signed-in user. In application-only access, the calling app must be assigned the *User.ReadWrite.All* application permission and at least the *User Administrator* [Azure AD role](/azure/active-directory/roles/permissions-reference).| |pastProjects|String collection|A list for the user to enumerate their past projects.| |postalCode|String|The postal code for the user's postal address. The postal code is specific to the user's country/region. In the United States of America, this attribute contains the ZIP code.| |preferredLanguage|String|The preferred language for the user. Should follow ISO 639-1 Code; for example `en-US`.| In the request body, supply the values for relevant fields that should be update |userType|String|A string value that can be used to classify user types in your directory, such as `Member` and `Guest`. | > [!NOTE] -> - The following properties cannot be updated by an app with only application permissions: **aboutMe**, **birthday**, **employeeHireDate**, **interests**, **mySite**, **pastProjects**, **preferredName**, **responsibilities**, **schools**, and **skills**. -> - To update the following properties, you must specify them in their own PATCH request, without including the other properties listed in the table above: **aboutMe**, **birthday**, **interests**, **mySite**, **pastProjects**, **preferredName**, **responsibilities**, **schools**, and **skills**. +> - The following properties cannot be updated by an app with only application permissions: **aboutMe**, **birthday**, **employeeHireDate**, **interests**, **mySite**, **pastProjects**, **responsibilities**, **schools**, and **skills**. +> - To update the following properties, you must specify them in their own PATCH request, without including the other properties listed in the table above: **aboutMe**, **birthday**, **interests**, **mySite**, **pastProjects**, **responsibilities**, **schools**, and **skills**. ### Manage extensions and associated data HTTP/1.1 204 No Content ### Example 3: Update the passwordProfile of a user to reset their password -The following example shows a request to reset the password of another user. The calling user must be assigned the *Directory.AccessAsUser.All* delegated permission to update this property. +The following example shows a request to reset the password of another user. #### Request |
| v1.0 | Serviceprincipal | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/v1.0/resources/serviceprincipal.md | This resource supports using [delta query](/graph/delta-query-overview) to track |[Get servicePrincipal](../api/serviceprincipal-get.md) | [servicePrincipal](serviceprincipal.md) |Read properties and relationships of servicePrincipal object.| |[Update servicePrincipal](../api/serviceprincipal-update.md) | [servicePrincipal](serviceprincipal.md) |Update servicePrincipal object. | |[Delete servicePrincipal](../api/serviceprincipal-delete.md) | None |Delete servicePrincipal object.|+|[List deleted servicePrincipals](../api/directory-deleteditems-list.md) | [directoryObject](directoryobject.md) collection | Retrieve a list of recently deleted servicePrincipal objects. | +|[Get deleted servicePrincipal](../api/directory-deleteditems-get.md) | [directoryObject](directoryobject.md) | Retrieve the properties of a recently deleted servicePrincipal object. | +|[Permanently delete servicePrincipal](../api/directory-deleteditems-delete.md) | None | Permanently delete a servicePrincipal object. | +|[Restore deleted servicePrincipal](../api/directory-deleteditems-restore.md) | [directoryObject](directoryobject.md) | Restore a recently deleted servicePrincipal object. | |[List createdObjects](../api/serviceprincipal-list-createdobjects.md) |[directoryObject](directoryobject.md) collection| Get a createdObject object collection.| |[List ownedObjects](../api/serviceprincipal-list-ownedobjects.md) |[directoryObject](directoryobject.md) collection| Get an ownedObject object collection.| |[Get delta](../api/serviceprincipal-delta.md)|servicePrincipal collection| Get incremental changes for service principals. | |
| v1.0 | User | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/v1.0/resources/user.md | This resource supports: |onPremisesProvisioningErrors|[onPremisesProvisioningError](onpremisesprovisioningerror.md) collection| Errors when using Microsoft synchronization product during provisioning. <br><br>Returned only on `$select`. Supports `$filter` (`eq`, `not`, `ge`, `le`).| |onPremisesSamAccountName|String| Contains the on-premises `samAccountName` synchronized from the on-premises directory. The property is only populated for customers who are synchronizing their on-premises directory to Azure Active Directory via Azure AD Connect. Read-only. <br><br>Returned only on `$select`. Supports `$filter` (`eq`, `ne`, `not`, `ge`, `le`, `in`, `startsWith`).| |onPremisesSecurityIdentifier|String|Contains the on-premises security identifier (SID) for the user that was synchronized from on-premises to the cloud. Read-only. <br><br>Returned only on `$select`. Supports `$filter` (`eq` including on `null` values). |-|onPremisesSyncEnabled|Boolean| `true` if this object is synced from an on-premises directory; `false` if this object was originally synced from an on-premises directory but is no longer synced; `null` if this object has never been synced from an on-premises directory (default). Read-only. <br><br>Returned only on `$select`. Supports `$filter` (`eq`, `ne`, `not`, `in`, and `eq` on `null` values).| +|onPremisesSyncEnabled|Boolean| `true` if this user object is currently being synced from an on-premises Active Directory (AD); otherwise the user isn't being synced and can be managed in Azure Active Directory (Azure AD). Read-only. <br><br>Returned only on `$select`. Supports `$filter` (`eq`, `ne`, `not`, `in`, and `eq` on `null` values).| |onPremisesUserPrincipalName|String| Contains the on-premises `userPrincipalName` synchronized from the on-premises directory. The property is only populated for customers who are synchronizing their on-premises directory to Azure Active Directory via Azure AD Connect. Read-only. <br><br>Returned only on `$select`. Supports `$filter` (`eq`, `ne`, `not`, `ge`, `le`, `in`, `startsWith`).| |otherMails|String collection| A list of additional email addresses for the user; for example: `["bob@contoso.com", "Robert@fabrikam.com"]`. <br>NOTE: This property cannot contain accent characters. <br><br>Returned only on `$select`. Supports `$filter` (`eq`, `not`, `ge`, `le`, `in`, `startsWith`, `endsWith`, and counting empty collections).| |passwordPolicies|String|Specifies password policies for the user. This value is an enumeration with one possible value being `DisableStrongPassword`, which allows weaker passwords than the default policy to be specified. `DisablePasswordExpiration` can also be specified. The two may be specified together; for example: `DisablePasswordExpiration, DisableStrongPassword`. <br><br>Returned only on `$select`. For more information on the default password policies, see [Azure AD pasword policies](/azure/active-directory/authentication/concept-sspr-policy#password-policies-that-only-apply-to-cloud-user-accounts). Supports `$filter` (`ne`, `not`, and `eq` on `null` values).| This resource supports: |postalCode|String|The postal code for the user's postal address. The postal code is specific to the user's country/region. In the United States of America, this attribute contains the ZIP code. Maximum length is 40 characters. <br><br>Returned only on `$select`. Supports `$filter` (`eq`, `ne`, `not`, `ge`, `le`, `in`, `startsWith`, and `eq` on `null` values).| | preferredDataLocation | String | The preferred data location for the user. For more information, see [OneDrive Online Multi-Geo](/sharepoint/dev/solution-guidance/multigeo-introduction).| |preferredLanguage|String|The preferred language for the user. Should follow ISO 639-1 Code; for example `en-US`. <br><br>Returned by default. Supports `$filter` (`eq`, `ne`, `not`, `ge`, `le`, `in`, `startsWith`, and `eq` on `null` values)|-|preferredName|String|The preferred name for the user. <br><br>Returned only on `$select`.| +|preferredName|String|The preferred name for the user. **Not Supported. This attribute returns an empty string.**<br><br>Returned only on `$select`.| |provisionedPlans|[provisionedPlan](provisionedplan.md) collection|The plans that are provisioned for the user. Read-only. Not nullable. <br><br>Returned only on `$select`. Supports `$filter` (`eq`, `not`, `ge`, `le`).| |proxyAddresses|String collection|For example: `["SMTP: bob@contoso.com", "smtp: bob@sales.contoso.com"]`. Changes to the **mail** property will also update this collection to include the value as an SMTP address. For more information, see [mail and proxyAddresses properties](#mail-and-proxyaddresses-properties). The proxy address prefixed with `SMTP` (capitalized) is the primary proxy address while those prefixed with `smtp` are the secondary proxy addresses. For Azure AD B2C accounts, this property has a limit of ten unique addresses. Read-only in Microsoft Graph; you can update this property only through the [Microsoft 365 admin center](/exchange/recipients-in-exchange-online/manage-user-mailboxes/add-or-remove-email-addresses). Not nullable. <br><br>Returned only on `$select`. Supports `$filter` (`eq`, `not`, `ge`, `le`, `startsWith`, `endsWith`, and counting empty collections).| |refreshTokensValidFromDateTime|DateTimeOffset|Any refresh tokens or sessions tokens (session cookies) issued before this time are invalid, and applications will get an error when using an invalid refresh or sessions token to acquire a delegated access token (to access APIs such as Microsoft Graph). If this happens, the application will need to acquire a new refresh token by making a request to the authorize endpoint. <br><br>Returned only on `$select`. Read-only. | |
| v1.0 | Toc.Yml | https://github.com/microsoftgraph/microsoft-graph-docs/commits/main/api-reference/v1.0/toc.yml | a/api-reference/v1.0/toc.yml items: href: api/serviceprincipal-update.md - name: Delete href: api/serviceprincipal-delete.md+ - name: List deleted service principals + href: api/directory-deleteditems-list.md + - name: Get deleted service principal + href: api/directory-deleteditems-get.md + - name: Permanently delete service principal + href: api/directory-deleteditems-delete.md + - name: Restore deleted service principal + href: api/directory-deleteditems-restore.md - name: Get delta href: api/serviceprincipal-delta.md - name: List created objects |