managementRoles

Management Roles. Named sets of admin permissions you can assign to principals. The managementRoles entity set lives under /exchange/v1.0/managementRoles in the Roles & access category.

Fact	Value
Path	`/exchange/v1.0/managementRoles`
Category	Roles & access
Tier	Tier 2, Exchange RBAC
Read role	`Rbac.Read.All` (Community)
Write role	`Rbac.ReadWrite.All` (Enterprise)
Backing cmdlets	Get-ManagementRole, New-ManagementRole, Remove-ManagementRole

Routes

Method	Path	Synopsis	Role	Plan
GET	`/exchange/v1.0/managementRoles`	List managementRoles entries.	`Rbac.Read`	Community
POST	`/exchange/v1.0/managementRoles`	Create a new managementRoles entry. Body keys map 1:1 to the cmdlet’s parameter names (camelCased). Returns 201 + Location + the freshly-fetched entity. Use ?dryRun=true to map to -WhatIf without applying.	`Rbac.ReadWrite`	Enterprise
GET	`/exchange/v1.0/managementRoles/{key}`	Get a single managementRoles entry by Identity.	`Rbac.Read`	Community
DELETE	`/exchange/v1.0/managementRoles/{key}`	DELETE /managementRoles/{key}. Use ?recurse=true to also remove child roles (Remove-ManagementRole -Recurse) and ?force=true to skip the confirmation guard.	`Rbac.ReadWrite`	Enterprise

GET /exchange/v1.0/managementRoles

List managementRoles entries.

Backing cmdlet: Get-ManagementRole. Role: Rbac.Read (Community).

Parameter	In	Type	Description
`cmdlet`	query	string	Return only roles that include the specified cmdlet (e.g. ?cmdlet=Set-Mailbox) - the ‘who can run X’ least-privilege query. Maps to Get-ManagementRole -Cmdlet.
`roleType`	query	string	Return only roles that match the specified role type (e.g. ?roleType=UnScopedTopLevel). Maps to Get-ManagementRole -RoleType.
`cmdletParameters`	query	string	Comma-separated cmdlet parameter names; returns only roles that include all of the specified parameters (e.g. ?cmdletParameters=Identity,Database). Maps to Get-ManagementRole -CmdletParameters.
`script`	query	string	Return only roles that include the specified script (e.g. ?script=Get-Foo.ps1). Maps to Get-ManagementRole -Script.
`scriptParameters`	query	String[]	Comma-separated script parameter names; returns only roles that include all of the specified script parameters. Maps to Get-ManagementRole -ScriptParameters.

List managementRoles

Stub auto-generated example for the managementRoles collection. Backing cmdlet: Get-ManagementRole. Live-verify with ?$top=3&$select=Id,Name and replace the synthetic body before promoting to Tier 1.

GET /exchange/v1.0/managementRoles?$top=3 HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#managementRoles",
  "value": []
}

Notes: Illustrative example derived from the cmdlet documentation, not a live capture: field names are real, values are placeholders.

POST /exchange/v1.0/managementRoles

Create a new managementRoles entry. Body keys map 1:1 to the cmdlet’s parameter names (camelCased). Returns 201 + Location + the freshly-fetched entity. Use ?dryRun=true to map to -WhatIf without applying.

Backing cmdlet: New-ManagementRole. Role: Rbac.ReadWrite (Enterprise).

Parameter	In	Type	Required	Description
`name`	body		yes
`description`	body
`enabledCmdlets`	body
`parent`	body
`dryRun`	query	bool (switch)
`force`	query	bool (switch)		Suppress warning/confirmation prompts when creating the role. Maps -Force on New-ManagementRole; for unattended programmatic creation.

Create a management role without the required name

Posting to New-ManagementRole without the required name field is rejected before the cmdlet runs. The name field is the only required parameter for New-ManagementRole.

POST /exchange/v1.0/managementRoles HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "parent": "Mail Recipients",
  "description": "Missing the required name field."
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "BadRequest",
    "message": "The 'name' field is required for New-ManagementRole.",
    "target": "name"
  },
  "correlationId": "0HN3Q5K7VJ2A1:00000007"
}

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

Create a management role

Creates a new Exchange RBAC management role by invoking New-ManagementRole. A new role is created as a child of an existing parent role (then trimmed with Remove-ManagementRoleEntry) or as an unscoped top-level role.

POST /exchange/v1.0/managementRoles HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "exonaut-sample-managementRoles",
  "parent": "Mail Recipients",
  "description": "EXONAUT sample management role derived from the Mail Recipients parent role."
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/managementRoles/exonaut-sample-managementRoles

{
  "Id": "exonaut-sample-managementRoles",
  "Identity": "exonaut-sample-managementRoles",
  "Name": "exonaut-sample-managementRoles",
  "Parent": "Mail Recipients",
  "Description": "EXONAUT sample management role derived from the Mail Recipients parent role."
}

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

GET /exchange/v1.0/managementRoles/{key}

Get a single managementRoles entry by Identity.

Backing cmdlet: Get-ManagementRole. Role: Rbac.Read (Community).

Parameter	In	Type	Description
`getChildren`	query	bool (switch)	Also return the immediate child roles of this role (the parent itself is not included). Maps to Get-ManagementRole -GetChildren. Mutually exclusive with recurse.
`recurse`	query	bool (switch)	Return this role plus its full descendant subtree (child roles and their children). Maps to Get-ManagementRole -Recurse. Mutually exclusive with getChildren.
`roleType`	query	string	Also restrict the result to roles of the given role type (e.g. ?roleType=UnScopedTopLevel). Maps to Get-ManagementRole -RoleType.

Get a single managementRoles entry

Stub auto-generated example for GET /managementRoles/{key}. Backing cmdlet: Get-ManagementRole with -Identity {key}. Returns the full entity body; 404 if the identity doesn’t resolve.

GET /exchange/v1.0/managementRoles/{key} HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#managementRoles/$entity"
}

Notes: Illustrative example derived from the cmdlet documentation, not a live capture: field names are real, values are placeholders.

DELETE /exchange/v1.0/managementRoles/{key}

DELETE /managementRoles/{key}. Use ?recurse=true to also remove child roles (Remove-ManagementRole -Recurse) and ?force=true to skip the confirmation guard.

Backing cmdlet: Remove-ManagementRole. Role: Rbac.ReadWrite (Enterprise).

Parameter	In	Type
`recurse`	query	bool (switch)
`force`	query	bool (switch)
`dryRun`	query	bool (switch)

Delete a management role

Removes an Exchange RBAC management role by invoking Remove-ManagementRole. Use ?recurse=true to also remove child roles and ?force=true to skip the confirmation guard.

DELETE /exchange/v1.0/managementRoles/{key} HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

HTTP/1.1 204 No Content

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

?dryRun=true previews of any write stay on Community.