add permission model and add sharing article

.openpublishing.redirection.json

@@ -227,7 +227,12 @@
     },
     {
       "source_path": "docs/embedded/concepts/app-concepts/sharing-and-perm.md",
-      "redirect_url": "/sharepoint/dev/embedded/development/sharing-and-perm",
+      "redirect_url": "/sharepoint/dev/embedded/development/sharing",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "docs/embedded/development/sharing-and-perm.md",
+      "redirect_url": "/sharepoint/dev/embedded/development/sharing",
       "redirect_document_id": false
     },
     {

docs/embedded/administration/consuming-tenant-admin/ctaUX.md

@@ -64,7 +64,7 @@ The detailed container view provides a deeper dive into container-specific metad
 1. **Membership:** This panel shows the user permissions for different users associated with the container. The admin can manage the membership on a container through this panel.
 
 > [!IMPORTANT]
-> The SharePoint Embedded platform supports four distinct [roles](../../development/sharing-and-perm.md): Owner, Manager, Writer, and Reader. The SharePoint Embedded application on your tenant may not use all four roles and might refer to these roles using different names.
+> The SharePoint Embedded platform supports four distinct [roles](../../development/permission-model.md): Owner, Manager, Writer, and Reader. The SharePoint Embedded application on your tenant may not use all four roles and might refer to these roles using different names.
 
 ![SharePoint Embedded Membership Roles](../../images/ctaux5.png)
 

docs/embedded/development/auth.md

@@ -123,7 +123,7 @@ Membership to a container [grants users container permissions](/graph/api/filest
 Specific items in a container can be shared with users via the [driveItem invite](/graph/api/driveitem-invite) or the [permission create](/graph/api/driveitem-post-permissions) endpoints. Sharing grants users access to the specific items, but it doesn't grant them access to the container itself or any other item in the container. For information on the access levels supported, see [permission roles](/graph/api/resources/permission#roles-property-values).
 
 > [!NOTE]
-> For more information about sharing, see [Sharing and permissions in SharePoint Embedded](./sharing-and-perm.md).
+> For more information about sharing, see [Share content in SharePoint Embedded](./sharing.md).
 
 #### Managing SharePoint Embedded applications installed in the consuming tenant
 

docs/embedded/development/permission-model.md

@@ -0,0 +1,133 @@
+---
+title: SharePoint Embedded permission model
+description: Learn how to grant access to containers, folders, and files in SharePoint Embedded (SPE), and how to break inheritance when an item needs its own permissions.
+author: cindylay
+ms.author: cindylay
+ms.service: sharepoint-embedded
+ms.topic: concept-article
+ms.date: 06/04/2026
+ms.localizationpriority: high
+---
+
+# SharePoint Embedded permission model
+
+In SharePoint Embedded (SPE), you grant access to a container, a folder, or a file. By default, permissions flow down: a folder picks up its container's access, and a file picks up its folder's access. The level you choose sets the reach of the grant:
+
+- Grant on the container, and the user gets that access on every folder and file in it.
+- Grant on a folder, and the user gets that access on that folder and everything under it.
+- Grant on a file, and the user gets that access on the file alone.
+
+A grant is additive. It adds to whatever access the user already has from grants higher up the tree. When the default flow doesn't fit a particular folder or file, you can break inheritance on that item so its permissions are independent of the folder it sits in.
+
+In this article, you learn how to:
+
+- Grant access to a container with one of four built-in roles.
+- Grant access to a folder and everything in it.
+- Grant access to a single file.
+- Break inheritance to give a folder or file independent permissions.
+- Predict what happens to permissions when you copy or move an item.
+
+## Granting access to a container and everything in it
+
+To give a user or group access to everything in a container, assign them one of four built-in container roles:
+
+| Role | What the user can do |
+|------|---------------------|
+| **Reader** | Read container content. |
+| **Writer** | Reader access, plus create and modify content. |
+| **Manager** | Writer access, plus manage container membership. |
+| **Owner** | Manager access, plus delete and restore the container itself. |
+
+A container role grants that role's access across the container's content by default. As folders and files are added, they pick up the role automatically through inheritance.
+
+For the full role definitions, see [Authentication and authorization with SharePoint Embedded](./auth.md).
+
+## Granting access to a folder and everything in it
+
+To give a user or group access to a single folder and everything under it, call a Microsoft Graph permission API on the folder. The API you use depends on who you're granting to.
+
+### For a user or guest
+
+Call [`driveItem: invite`](/graph/api/driveitem-invite) on the folder.
+
+SPE rules:
+
+- Set `sendInvitation` to `false`. SPE doesn't deliver invitation emails.
+- New guest users require delegated permissions. Inviting an existing guest (already in the consuming tenant's directory) works with either delegated or application permissions.
+
+### For a SharePoint group
+
+Call [`driveItem: createPermission`](/graph/api/driveitem-post-permissions) on the folder.
+
+SPE rules:
+
+- Use app-only auth. SPE only supports `createPermission` with app-only.
+- SPE only accepts `sharePointGroup` permissions on this call. Other principal types are rejected.
+
+### What the new permission does
+
+The new permission applies to the folder. Subfolders and files inside the folder pick up the permission too, as long as they still inherit. A child folder or file with broken inheritance doesn't pick up the new permission.
+
+The new permission adds to the folder's existing permissions. It doesn't replace them, and it doesn't break the folder's inheritance from the container.
+
+To see the permissions on an item, use [List permissions](/graph/api/driveitem-list-permissions). To remove a permission, use [Delete permission](/graph/api/permission-delete). You can only delete a permission on the item where it was granted. You can't delete an inherited permission from a child item.
+
+## Granting access to a single file
+
+To give a user or group access to one file, call the same APIs on the file:
+
+- [`driveItem: invite`](/graph/api/driveitem-invite) for a user or guest.
+- [`driveItem: createPermission`](/graph/api/driveitem-post-permissions) for a SharePoint group.
+
+The same SPE rules apply (see [Granting access to a folder and everything in it](#granting-access-to-a-folder-and-everything-in-it)). The new permission applies to the file alone, on top of whatever access the file already inherits from its parent folder and container.
+
+## Breaking inheritance
+
+> [!WARNING]
+> Breaking inheritance is hard to undo. Avoid it unless you specifically need a folder or file to have permissions that don't follow its parent. For most scenarios, a regular grant on the item is enough, because the grant adds to what the user already has.
+
+To break inheritance on a folder or file, call [`driveItem: invite`](/graph/api/driveitem-invite) on the item with `retainInheritedPermissions` set to `false`. The parameter defaults to `true`, which is why regular grants don't break inheritance.
+
+After the break:
+
+- Container members keep access. Container-role assignments (Owner, Manager, Writer, Reader) always apply, even on items with broken inheritance.
+- SPE drops the item-level permissions the item was inheriting from its parent folder and keeps only the ones you specify in the call.
+- The item stops picking up item-level changes from its parent folder. Later grants on the parent folder don't reach the item.
+- Anyone who reached the item only through an item-level grant on a parent folder loses access on the item. Add them back explicitly if they still need it.
+- Subfolders and files under the item still inherit, but they now inherit from the item's independent permissions instead of the parent chain.
+
+You can break inheritance on a folder or a file. There's no API to break inheritance at the container itself.
+
+## Copy and move behavior
+
+What happens to permissions during a copy or move depends on where the item ends up.
+
+### Move within the same container
+
+When you move an item within its current container using [`driveItem: move`](/graph/api/driveitem-move):
+
+- Permissions set directly on the item are preserved at the destination.
+- If the item still inherits, it picks up the destination parent folder's permissions.
+- If the item has broken inheritance, it keeps its independent permissions and doesn't start inheriting from the new parent folder.
+- Container-role assignments still apply, because the item is still in the same container.
+
+### Move across containers
+
+When you move an item to a different container using [`driveItem: move`](/graph/api/driveitem-move), only the file or folder transfers. None of the source item's permissions come with it. At the destination, the item starts fresh: no permissions of its own, picking up access only from the destination container and parent folder.
+
+### Copy
+
+Copying an item, in the same container or across containers, produces a new item at the destination. The new item starts with no permissions of its own and picks up access only from its destination container and parent folder.
+
+To give the new or moved item any direct access at the destination, add permissions explicitly with [`driveItem: invite`](/graph/api/driveitem-invite) or [`driveItem: createPermission`](/graph/api/driveitem-post-permissions).
+
+
+## Related content
+
+- [Share content in SharePoint Embedded](./sharing.md)
+- [Authentication and authorization with SharePoint Embedded](./auth.md)
+- [`driveItem: invite`](/graph/api/driveitem-invite)
+- [`driveItem: createPermission`](/graph/api/driveitem-post-permissions)
+- [`driveItem: move`](/graph/api/driveitem-move)
+- [List permissions](/graph/api/driveitem-list-permissions)
+- [Delete permission](/graph/api/permission-delete)