Least-privilege app-only access: grant an app (by client id) a role on one site (Sites.Selected) or one list (Lists.SelectedOperations.Selected), list the grants, change and revoke them. For single files and folders (Files.SelectedOperations.Selected) use ::microsoft::onedrive::sharing/grant-app.

This is an admin step. The granting call needs Sites.FullControl.All (application, or delegated for a SharePoint Administrator who is a member of the site); the app being granted only needs Sites.Selected (or the list/file scope) consented in Entra ID. Usually a separate admin tool or a one-off run with an admin app does the granting; your production app never holds Sites.FullControl.All.

All three steps are required for access: (1) the Selected scope is admin-consented for the app, (2) a grant exists on the resource, (3) the app's token carries the scope.

Roles: read, write, owner, fullcontrol.

Values

`ROLES`

ROLES: Vec [
  "read",
  "write",
  "owner",
  "fullcontrol"
]

Functions

`build-list-grant`

fn (app-id: Str, display-name: Str?, roles: Vec): Map

The body of a list grant (pure): {roles, grantedToV2: {application: {id, displayName}}}, the documented shape for POST /sites/{id}/lists/{id}/permissions.

`build-site-grant`

fn (app-id: Str, display-name: Str?, roles: Vec): Map

The body of a site grant (pure): {roles, grantedToIdentities: [{application: {id, displayName}}]}, the documented shape for POST /sites/{id}/permissions.

`check-roles`

fn (roles: Vec): Vec

`delete-list-grant`

fn (site-id: Str, list: Str, permission-id: Str): Bool
fn (site-id: Str, list: Str, permission-id: Str, opts: Map): Bool

DELETE /sites/{site-id}/lists/{list}/permissions/{id} - revoke a list grant. Returns true.

`delete-site-grant`

fn (site-id: Str, permission-id: Str): Bool
fn (site-id: Str, permission-id: Str, opts: Map): Bool

DELETE /sites/{site-id}/permissions/{id} - revoke an app's access to the site. Returns true.

`get-site-grant`

fn (site-id: Str, permission-id: Str): Map
fn (site-id: Str, permission-id: Str, opts: Map): Map

GET /sites/{site-id}/permissions/{id}.

`grant-list`

fn (site-id: Str, list: Str, app-id: Str, display-name: Str?, roles: Vec): Map
fn (site-id: Str, list: Str, app-id: Str, display-name: Str?, roles: Vec, opts: Map): Map

POST /sites/{site-id}/lists/{list}/permissions - grant an app roles on one list, for an app consented Lists.SelectedOperations.Selected. Breaks permission inheritance on the list. Returns the permission.

`grant-site`

fn (site-id: Str, app-id: Str, display-name: Str?, roles: Vec): Map
fn (site-id: Str, app-id: Str, display-name: Str?, roles: Vec, opts: Map): Map

POST /sites/{site-id}/permissions - grant app app-id (its client id) roles on a site, for an app consented Sites.Selected. Needs Sites.FullControl.All. Returns the permission (keep its id to revoke).

// Run once with an admin app's credentials
grant ::microsoft::sharepoint::permissions/grant-site(site-id, "11111111-2222-3333-4444-555555555555", "Contoso Indexer", ["read"], {
  client-id: admin-app-id, client-secret: admin-secret, tenant-id: "contoso.onmicrosoft.com"
})
grant.id

`list-list-grants`

fn (site-id: Str, list: Str): Vec
fn (site-id: Str, list: Str, opts: Map): Vec

GET /sites/{site-id}/lists/{list}/permissions - the permissions on a list.

`list-site-grants`

fn (site-id: Str): Vec
fn (site-id: Str, opts: Map): Vec

GET /sites/{site-id}/permissions - the app grants on a site (id, roles, grantedToIdentitiesV2). Needs Sites.FullControl.All.

`perm-json`

fn (method: Str, path: Str, body: Any, opts: Map): Any

`update-site-grant`

fn (site-id: Str, permission-id: Str, roles: Vec): Map
fn (site-id: Str, permission-id: Str, roles: Vec, opts: Map): Map

PATCH /sites/{site-id}/permissions/{id} - change a grant's roles (e.g. raise read to write). Returns the permission.

::lists ::sites