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.

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
`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": ""
}

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
`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": "admin@contoso.com"
}

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": [
    "admin@contoso.com"
  ]
}

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
`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": []
}

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
`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": [
    "admin@contoso.com",
    "user@contoso.com"
  ]
}

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.

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
`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": "user@contoso.com"
}

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.

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.

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