servicePrincipals

App Service Principals. App identities registered for Exchange role-based access. The servicePrincipals entity set lives under /exchange/v1.0/servicePrincipals in the Roles & access category.

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

Routes

Method	Path	Synopsis	Role	Plan
GET	`/exchange/v1.0/servicePrincipals`	List service principals known to Exchange RBAC - Entra apps + managed identities granted Exchange roles.	`Rbac.Read`	Community
POST	`/exchange/v1.0/servicePrincipals`	POST /servicePrincipals - register an Entra app SP with EXO RBAC. Required: appId (Entra app id), objectId (Entra SP object id), serviceId (Exchange identifier; typically same as objectId). Returns 201 + Location.	`Rbac.ReadWrite`	Enterprise
GET	`/exchange/v1.0/servicePrincipals/{key}`	Get a single service principal by Identity. Returns 404 if absent.	`Rbac.Read`	Community
PATCH	`/exchange/v1.0/servicePrincipals/{key}`	PATCH /servicePrincipals/{key} - update DisplayName. Set-ServicePrincipal only exposes one writable field per Wiki SYNTAX. Returns 200 + post-Set SP.	`Rbac.ReadWrite`	Enterprise
DELETE	`/exchange/v1.0/servicePrincipals/{key}`	DELETE /servicePrincipals/{key} - remove an EXO-side SP registration. Returns 204.	`Rbac.ReadWrite`	Enterprise

GET /exchange/v1.0/servicePrincipals

List service principals known to Exchange RBAC - Entra apps + managed identities granted Exchange roles.

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

List service principals known to Exchange RBAC

Returns the Entra apps and managed identities registered on the Exchange RBAC side, each with its AppId, ObjectId and Exchange identifiers. This is the EXO-side ServicePrincipal surface, not Graph /servicePrincipals.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#servicePrincipals",
  "value": [
    {
      "Id": "1a0982fb-31b2-4e46-bf6a-8f0db0b8ad18",
      "AppId": "6c711892-7541-444c-a3f5-3f81714cee3d",
      "DisplayName": "CloudM_Test",
      "ServiceId": null,
      "ExchangeObjectId": "071281b6-005d-4298-a324-5f787ae8a203",
      "DistinguishedName": "CN=1a0982fb-31b2-4e46-bf6a-8f0db0b8ad18,OU=contoso.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "Guid": "071281b6-005d-4298-a324-5f787ae8a203",
      "Identity": "1a0982fb-31b2-4e46-bf6a-8f0db0b8ad18",
      "Name": "1a0982fb-31b2-4e46-bf6a-8f0db0b8ad18",
      "ObjectId": "1a0982fb-31b2-4e46-bf6a-8f0db0b8ad18",
      "OrganizationalUnitRoot": "contoso.onmicrosoft.com",
      "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
      "OverrideEnforceExoAppRbacPermissions": false,
      "Sid": "S-1-5-21-1885728323-2243858645-3579082151-19021538",
      "SidHistory": null,
      "WhenChanged": "2026-04-10T14:08:52+03:00",
      "WhenChangedUTC": "2026-04-10T11:08:52Z",
      "WhenCreated": "2026-04-10T14:08:48+03:00",
      "WhenCreatedUTC": "2026-04-10T11:08:48Z"
    },
    {
      "Id": "457d3beb-9eec-47c7-a741-5ba072c658a7",
      "AppId": "b0788f20-b3d9-4a64-b1a1-2f5caff2afac",
      "DisplayName": "MigrationWiz",
      "ServiceId": null,
      "ExchangeObjectId": "2c5b3eb4-447a-4841-b580-6ecb9cb22804",
      "DistinguishedName": "CN=457d3beb-9eec-47c7-a741-5ba072c658a7,OU=contoso.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "Guid": "0706de73-c445-4a56-ac91-eed91b452a60",
      "Identity": "457d3beb-9eec-47c7-a741-5ba072c658a7",
      "Name": "457d3beb-9eec-47c7-a741-5ba072c658a7",
      "ObjectId": "457d3beb-9eec-47c7-a741-5ba072c658a7",
      "OrganizationalUnitRoot": "contoso.onmicrosoft.com",
      "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
      "OverrideEnforceExoAppRbacPermissions": false,
      "Sid": "S-1-5-21-701439281-3420630407-1831248095-38688788",
      "SidHistory": "S-1-5-21-701439281-3420630407-1831248095-38688788",
      "WhenChanged": "2026-03-31T17:49:13+03:00",
      "WhenChangedUTC": "2026-03-31T14:49:13Z",
      "WhenCreated": "2026-03-31T17:46:48+03:00",
      "WhenCreatedUTC": "2026-03-31T14:46:48Z"
    },
    {
      "Id": "4916ac8f-a098-4bad-9e20-d326915998af",
      "AppId": "03b07b79-c5bc-4b5e-9bfa-13acf4a99998",
      "DisplayName": "UTCM",
      "ServiceId": null,
      "ExchangeObjectId": "e35364e6-5676-4351-b4d9-6458b77692d9",
      "DistinguishedName": "CN=4916ac8f-a098-4bad-9e20-d326915998af,OU=contoso.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "Guid": "9b9ea74e-0770-402f-96e5-d38a5f0dbf30",
      "Identity": "4916ac8f-a098-4bad-9e20-d326915998af",
      "Name": "4916ac8f-a098-4bad-9e20-d326915998af",
      "ObjectId": "4916ac8f-a098-4bad-9e20-d326915998af",
      "OrganizationalUnitRoot": "contoso.onmicrosoft.com",
      "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
      "OverrideEnforceExoAppRbacPermissions": false,
      "Sid": "S-1-5-21-701439281-3420630407-1831248095-40076457",
      "SidHistory": "S-1-5-21-701439281-3420630407-1831248095-40076457",
      "WhenChanged": "2026-03-31T17:54:29+03:00",
      "WhenChangedUTC": "2026-03-31T14:54:29Z",
      "WhenCreated": "2026-03-31T17:51:37+03:00",
      "WhenCreatedUTC": "2026-03-31T14:51:37Z"
    }
  ]
}

POST /exchange/v1.0/servicePrincipals

POST /servicePrincipals - register an Entra app SP with EXO RBAC. Required: appId (Entra app id), objectId (Entra SP object id), serviceId (Exchange identifier; typically same as objectId). Returns 201 + Location.

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

Parameter	In	Type	Required
`appId`	body		yes
`objectId`	body		yes
`serviceId`	body		yes
`displayName`	body
`dryRun`	query	bool (switch)

Register an Entra app with EXO RBAC

Register an Entra app’s SP with Exchange’s RBAC system so it becomes eligible for Exchange management role assignments. NOT the same as Graph /servicePrincipals - this is the EXO-side integration object. Three identifiers required: appId (Entra app id), objectId (Entra SP object id from Graph), serviceId (Exchange identifier; conventionally the same value as objectId). After create, grant Exchange roles via POST /managementRoleAssignments with this SP’s ServiceId as the assignee.

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

{
  "appId": "47a4123a-fc63-4b9a-8e3f-9b3a91b53b2f",
  "objectId": "a1b2c3d4-1234-5678-9abc-def012345678",
  "serviceId": "a1b2c3d4-1234-5678-9abc-def012345678",
  "displayName": "Contoso Backup Automation"
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/servicePrincipals/a1b2c3d4-1234-5678-9abc-def012345678

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#servicePrincipals/$entity",
  "Id": "a1b2c3d4-1234-5678-9abc-def012345678",
  "AppId": "47a4123a-fc63-4b9a-8e3f-9b3a91b53b2f",
  "ServiceId": "a1b2c3d4-1234-5678-9abc-def012345678",
  "DisplayName": "Contoso Backup Automation",
  "ExchangeObjectId": "11ff22ee-3344-5566-7788-99aabbccddee"
}

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

Get a single service principal by Identity. Returns 404 if absent.

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

Get an Exchange RBAC service principal by id

Returns a single EXO-side ServicePrincipal - the link object between an Entra app registration and Exchange management role assignments - looked up by its Identity. This is not the Graph /servicePrincipals object; it carries AppId, ServiceId and the Exchange directory attributes.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#servicePrincipals/$entity",
  "Id": "1a0982fb-31b2-4e46-bf6a-8f0db0b8ad18",
  "AppId": "6c711892-7541-444c-a3f5-3f81714cee3d",
  "DisplayName": "CloudM_Test",
  "ServiceId": null,
  "ExchangeObjectId": "071281b6-005d-4298-a324-5f787ae8a203",
  "DistinguishedName": "CN=1a0982fb-31b2-4e46-bf6a-8f0db0b8ad18,OU=contoso.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "Guid": "071281b6-005d-4298-a324-5f787ae8a203",
  "Identity": "1a0982fb-31b2-4e46-bf6a-8f0db0b8ad18",
  "Name": "1a0982fb-31b2-4e46-bf6a-8f0db0b8ad18",
  "ObjectId": "1a0982fb-31b2-4e46-bf6a-8f0db0b8ad18",
  "OrganizationalUnitRoot": "contoso.onmicrosoft.com",
  "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
  "OverrideEnforceExoAppRbacPermissions": false,
  "Sid": "S-1-5-21-1885728323-2243858645-3579082151-19021538",
  "SidHistory": null,
  "WhenChanged": "2026-04-10T14:08:52+03:00",
  "WhenChangedUTC": "2026-04-10T11:08:52Z",
  "WhenCreated": "2026-04-10T14:08:48+03:00",
  "WhenCreatedUTC": "2026-04-10T11:08:48Z"
}

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

PATCH /servicePrincipals/{key} - update DisplayName. Set-ServicePrincipal only exposes one writable field per Wiki SYNTAX. Returns 200 + post-Set SP.

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

Parameter	In	Type	Required	Description
`displayName`	body
`dryRun`	query	bool (switch)

Update a service principal display name

Update the display name of an EXO-side service principal registration via Set-ServicePrincipal. Per the Wiki SYNTAX, displayName is the only writable field. The {key} is the service principal Identity (ServiceId or ObjectId).

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

{
  "displayName": "exonaut-sample-servicePrincipals"
}

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

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#servicePrincipals/$entity",
  "Id": "a1b2c3d4-1234-5678-9abc-def012345678",
  "Identity": "a1b2c3d4-1234-5678-9abc-def012345678",
  "AppId": "47a4123a-fc63-4b9a-8e3f-9b3a91b53b2f",
  "ServiceId": "a1b2c3d4-1234-5678-9abc-def012345678",
  "DisplayName": "exonaut-sample-servicePrincipals",
  "ExchangeObjectId": "11ff22ee-3344-5566-7788-99aabbccddee"
}

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

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

DELETE /servicePrincipals/{key} - remove an EXO-side SP registration. Returns 204.

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

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

Remove a service principal registration

Remove an EXO-side service principal registration via Remove-ServicePrincipal. The {key} is the service principal Identity (ServiceId or ObjectId). Returns 204 No Content on success.

DELETE /exchange/v1.0/servicePrincipals/{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.