roleGroups

Admin Role Groups. Groups that bundle management roles for assignment to admins. The roleGroups entity set lives under /exchange/v1.0/roleGroups in the Roles & access category.

Fact	Value
Path	/exchange/v1.0/roleGroups
Category	Roles & access
Tier	Tier 2, Exchange RBAC
Read role	Rbac.Read.All (Community)
Write role	Rbac.ReadWrite.All (Enterprise)
Backing cmdlets	Get-RoleGroup, Get-RoleGroupMember, New-RoleGroup, Set-RoleGroup, Remove-RoleGroup, Add-RoleGroupMember, Remove-RoleGroupMember, Update-RoleGroupMember

Routes

Method	Path	Synopsis	Role	Plan
GET	/exchange/v1.0/roleGroups	List roleGroups entries.	Rbac.Read	Community
POST	/exchange/v1.0/roleGroups	Create a new roleGroups 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/roleGroups/{key}	Get a single roleGroups entry by Identity.	Rbac.Read	Community
PATCH	/exchange/v1.0/roleGroups/{key}	PATCH /roleGroups/{key}. ?bypassSecurityGroupManagerCheck=true is exposed for tenants where the SP isn’t on the group’s ManagedBy list.	Rbac.ReadWrite	Enterprise
DELETE	/exchange/v1.0/roleGroups/{key}	Remove the roleGroups at /roleGroups/{key}. Returns 204 with no body.	Rbac.ReadWrite	Enterprise
GET	/exchange/v1.0/roleGroups/{key}/members	GET /roleGroups/{key}/members - the members of the role group at GET /roleGroups/{key}, via Get-RoleGroupMember -Identity {key}. Membership was previously only writable; this exposes it for reads. Returns polymorphic recipients.	Rbac.Read	Community
PUT	/exchange/v1.0/roleGroups/{key}/members	PUT /roleGroups/{key}/members - replaces the entire member set via Update-RoleGroupMember -Members <list>. Bulk-replace semantic; pass an empty members array to clear membership.	Rbac.ReadWrite	Enterprise
POST	/exchange/v1.0/roleGroups/{key}/members/$ref	POST /roleGroups/{key}/members/$ref - adds one member to the role group via Add-RoleGroupMember. Body: {“member”:“<identity>”}.	Rbac.ReadWrite	Enterprise
DELETE	/exchange/v1.0/roleGroups/{key}/members/{memberId}/$ref	DELETE /roleGroups/{key}/members/{memberId}/$ref - removes one member via Remove-RoleGroupMember.	Rbac.ReadWrite	Enterprise

GET /exchange/v1.0/roleGroups

List roleGroups entries.

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

Parameter	In	Type	Required	Description
all	query	bool (switch)		Return all results instead of the EXO default of 1000. Maps -ResultSize Unlimited on Get-RoleGroup; prevents silent truncation in large tenants.
showPartnerLinked	query	bool (switch)

List roleGroups

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

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

HTTP/1.1 200 OK

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

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

Related: GET /exchange/v1.0/roleGroups/{key}

POST /exchange/v1.0/roleGroups

Create a new roleGroups 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-RoleGroup. Role: Rbac.ReadWrite (Enterprise).

Parameter	In	Type	Required	Description
name	body		yes
customRecipientWriteScope	body
description	body
displayName	body
managedBy	body
members	body
roles	body
wellKnownObject	body
dryRun	query	bool (switch)

Create rbac role group - duplicate (409)

RBAC role group create returns 409 when an object of that name already exists. Backed by New-RoleGroup.

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

{
  "name": "exonaut-audit-rg"
}

HTTP/1.1 409 Conflict

{
  "error": {
    "code": "Conflict",
    "message": "Cmdlet 'New-RoleGroup' failed: ||Active Directory operation failed on VI1PR01A17DC001.EURPR01A017.PROD.OUTLOOK.COM. The object 'CN=exonaut-audit-rg,OU=contoso.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM' already exists.",
    "target": null,
    "innerError": {
      "cmdlet": "New-RoleGroup"
    }
  },
  "correlationId": "0HNLTJ0Q1D32B:00000001"
}

Create a rbac role group

RBAC role group create. Returns 201 + Location + the freshly-fetched object. Backed by New-RoleGroup.

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

{
  "name": "exonaut-audit-rg"
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/roleGroups/exonaut-audit-rg

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#roleGroups/$entity",
  "Id": "exonaut-audit-rg",
  "ExchangeGuid": "00000000-0000-0000-0000-000000000000",
  "Guid": "391b8a2c-3ec7-4742-87ba-40a65b1ce985",
  "DisplayName": "",
  "SimpleDisplayName": null,
  "PhoneticDisplayName": null,
  "Name": "exonaut-audit-rg",
  "Alias": null,
  "DistinguishedName": "CN=exonaut-audit-rg,OU=contoso.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "Identity": "exonaut-audit-rg",
  "ExternalDirectoryObjectId": "",
  "PrimarySmtpAddress": null,
  "WindowsLiveID": null,
  "WindowsEmailAddress": null,
  "EmailAddresses": [],
  "EmailAddressPolicyEnabled": false,
  "RecipientType": null,
  "RecipientTypeDetails": null,
  "OrganizationalUnit": null,
  "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
  "CustomAttribute1": null,
  "CustomAttribute2": null,
  "CustomAttribute3": null,
  "CustomAttribute4": null,
  "CustomAttribute5": null,
  "ExtensionCustomAttribute1": [],
  "ExtensionCustomAttribute2": [],
  "ExtensionCustomAttribute3": [],
  "ExtensionCustomAttribute4": [],
  "ExtensionCustomAttribute5": [],
  "HiddenFromAddressListsEnabled": false,
  "AddressBookPolicy": null,
  "WhenCreated": "2026-05-29T18:45:16+03:00",
  "WhenChanged": "2026-05-29T18:45:16+03:00",
  "WhenCreatedUTC": "2026-05-29T15:45:16Z",
  "WhenChangedUTC": "2026-05-29T15:45:16Z",
  "Description": "",
  "RoleGroupType": "Standard",
  "IsManageableByEndUser": false,
  "LinkedGroup": "",
  "ManagedBy": [
    "Organization Management"
  ],
  "ExternalDirectoryObjectIdRaw": null,
  "Roles": [],
  "RoleAssignments": [],
  "Members": [],
  "DelegatingGroup": [],
  "ExchangeVersion": "0.10 (14.0.100.0)",
  "ObjectCategory": "EURPR01A017.PROD.OUTLOOK.COM/Configuration/Schema/Group",
  "ObjectClass": [
    "top",
    "group"
  ],
  "OriginatingServer": "VI1PR01A17DC001.EURPR01A017.PROD.OUTLOOK.COM",
  "ObjectState": "Changed",
  "IsValid": true,
  "Capabilities": [],
  "ExchangeObjectId": "391b8a2c-3ec7-4742-87ba-40a65b1ce985",
  "LinkedPartnerGroupId": "",
  "LinkedPartnerOrganizationId": "",
  "OrganizationalUnitRoot": "contoso.onmicrosoft.com",
  "SamAccountName": "$TBOJI0-M78BMBLRGALC",
  "WellKnownObject": ""
}

Related: GET /exchange/v1.0/roleGroups, DELETE /exchange/v1.0/roleGroups/{key}

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

Get a single roleGroups entry by Identity.

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

Get a single roleGroups entry

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

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

HTTP/1.1 200 OK

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

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

Related: GET /exchange/v1.0/roleGroups

PATCH /exchange/v1.0/roleGroups/{key}

PATCH /roleGroups/{key}. ?bypassSecurityGroupManagerCheck=true is exposed for tenants where the SP isn’t on the group’s ManagedBy list.

Backing cmdlet: Set-RoleGroup. Role: Rbac.ReadWrite (Enterprise).

Parameter	In	Type	Required	Description
description	body
displayName	body
managedBy	body
name	body
wellKnownObject	body
bypassSecurityGroupManagerCheck	query	bool (switch)
force	query	bool (switch)
dryRun	query	bool (switch)

Update a role group’s display name and description

Updates mutable properties of an Exchange RBAC role group via Set-RoleGroup. The body carries only the cmdlet-accepted Set parameters, camelCased.

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

{
  "displayName": "Exonaut Sample Role Group",
  "description": "Updated by the Exonaut automation sample.",
  "managedBy": "[email protected]"
}

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal

{
  "Id": "exonaut-sample-roleGroups",
  "Identity": "exonaut-sample-roleGroups",
  "Name": "exonaut-sample-roleGroups",
  "DisplayName": "Exonaut Sample Role Group",
  "Description": "Updated by the Exonaut automation sample.",
  "ManagedBy": [
    "[email protected]"
  ]
}

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

Related: GET /exchange/v1.0/roleGroups

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

Remove the roleGroups at /roleGroups/{key}. Returns 204 with no body.

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

Parameter	In	Type	Required	Description
bypassSecurityGroupManagerCheck	query	bool (switch)
force	query	bool (switch)
dryRun	query	bool (switch)

Delete a rbac role group

Removes the rbac role group by Identity. Returns 204. Backed by Remove-RoleGroup.

DELETE /exchange/v1.0/roleGroups/{key} HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 204 No Content

Related: POST /exchange/v1.0/roleGroups

GET /exchange/v1.0/roleGroups/{key}/members

GET /roleGroups/{key}/members - the members of the role group at GET /roleGroups/{key}, via Get-RoleGroupMember -Identity {key}. Membership was previously only writable; this exposes it for reads. Returns polymorphic recipients.

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

Parameter	In	Type	Required	Description
all	query	bool (switch)		Return all members instead of the EXO default of 1000. Maps to -ResultSize Unlimited on Get-RoleGroupMember; prevents silent truncation in large role groups.
resultSize	query	int		Optional: max members returned (Get-RoleGroupMember -ResultSize; default 1000). Ignored when ?all=true.

List the members of a role group

Sub-resource of the role group at GET /roleGroups/{key} - returns the members (recipients) currently assigned to the role group identified by {key}. Backed by Get-RoleGroupMember -Identity {key}.

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

HTTP/1.1 200 OK

{
  "@odata.context": "https://contoso.com/exchange/v1.0/$metadata#roleGroups('Communication%20Compliance')/Members/ExchangeApi.Recipient",
  "value": []
}

Related: GET /exchange/v1.0/roleGroups/{key}, GET /exchange/v1.0/roleGroups

PUT /exchange/v1.0/roleGroups/{key}/members

PUT /roleGroups/{key}/members - replaces the entire member set via Update-RoleGroupMember -Members <list>. Bulk-replace semantic; pass an empty members array to clear membership.

Backing cmdlet: Update-RoleGroupMember. Role: Rbac.ReadWrite (Enterprise).

Parameter	In	Type	Required	Description
members	body	array
bypassSecurityGroupManagerCheck	query	bool (switch)
dryRun	query	bool (switch)

Replace the entire member set of a role group

Sub-resource of the role group at GET /roleGroups/{key} - bulk-replaces the role group’s complete membership via Update-RoleGroupMember -Members. Pass an empty members array to clear membership.

PUT /exchange/v1.0/roleGroups/{key}/members HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "members": [
    "[email protected]",
    "[email protected]"
  ]
}

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.

Related: GET /exchange/v1.0/roleGroups, POST /exchange/v1.0/roleGroups/{key}/members/$ref, DELETE /exchange/v1.0/roleGroups/{key}/members/{memberId}/$ref

POST /exchange/v1.0/roleGroups/{key}/members/$ref

POST /roleGroups/{key}/members/$ref - adds one member to the role group via Add-RoleGroupMember. Body: {“member”:“<identity>”}.

Backing cmdlet: Add-RoleGroupMember. Role: Rbac.ReadWrite (Enterprise).

Parameter	In	Type	Required	Description
member	body	string	yes
bypassSecurityGroupManagerCheck	query	bool (switch)
dryRun	query	bool (switch)

Add a member to a role group

Sub-resource of GET /roleGroups/{key}/members. Sub-resource of the role group at GET /roleGroups/{key} - adds one security principal to the role group’s membership via Add-RoleGroupMember. The body carries a single member identity.

POST /exchange/v1.0/roleGroups/{key}/members/$ref HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "member": "[email protected]"
}

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.

Related: GET /exchange/v1.0/roleGroups, DELETE /exchange/v1.0/roleGroups/{key}/members/{memberId}/$ref, PUT /exchange/v1.0/roleGroups/{key}/members

DELETE /exchange/v1.0/roleGroups/{key}/members/{memberId}/$ref

DELETE /roleGroups/{key}/members/{memberId}/$ref - removes one member via Remove-RoleGroupMember.

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

Parameter	In	Type	Required	Description
bypassSecurityGroupManagerCheck	query	bool (switch)
dryRun	query	bool (switch)

Remove a member from a role group

Sub-resource of GET /roleGroups/{key}/members/{memberId}. Sub-resource of the role group at GET /roleGroups/{key} - removes one security principal from the role group’s membership via Remove-RoleGroupMember. The member identity is the trailing path segment.

DELETE /exchange/v1.0/roleGroups/{key}/members/{memberId}/$ref 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.

Related: GET /exchange/v1.0/roleGroups, POST /exchange/v1.0/roleGroups/{key}/members/$ref, PUT /exchange/v1.0/roleGroups/{key}/members

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