In Microsoft Entra ID (formerly Azure AD), a service principal is the identity an application uses to access resources, and the Microsoft Graph service principal is the tenant-local representation of the Microsoft Graph API itself. It publishes the set of OAuth 2.0 delegated scopes and application roles (permissions) that apps can request, and it is the target against which your app’s own service principal is granted consent.
openapi: 3.1.0
info:
title: Microsoft Graph Serviceprincipals
description: Needs a description.
paths:
/servicePrincipals:
description: Provides operations to manage the collection of servicePrincipal entities.
get:
tags:
- servicePrincipals.servicePrincipal
summary: Microsoft Graph List servicePrincipals
description: Retrieve a list of servicePrincipal objects.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/serviceprincipal-list?view=graph-rest-1.0
operationId: servicePrincipals.servicePrincipal.ListServicePrincipal
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.servicePrincipalCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- servicePrincipals.servicePrincipal
summary: Microsoft Graph Create servicePrincipal
description: Create a new servicePrincipal object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/serviceprincipal-post-serviceprincipals?view=graph-rest-1.0
operationId: servicePrincipals.servicePrincipal.CreateServicePrincipal
requestBody:
description: New entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.servicePrincipal'
required: true
responses:
2XX:
description: Created entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.servicePrincipal'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/servicePrincipals/{servicePrincipal-id}:
description: Provides operations to manage the collection of servicePrincipal entities.
get:
tags:
- servicePrincipals.servicePrincipal
summary: Microsoft Graph Get servicePrincipal
description: Retrieve the properties and relationships of a servicePrincipal object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/serviceprincipal-get?view=graph-rest-1.0
operationId: servicePrincipals.servicePrincipal.GetServicePrincipal
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.servicePrincipal'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- servicePrincipals.servicePrincipal
summary: Microsoft Graph Upsert servicePrincipal
description: >-
Create a new servicePrincipal object if it doesn't exist, or update the
properties of an existing servicePrincipal object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/serviceprincipal-upsert?view=graph-rest-1.0
operationId: servicePrincipals.servicePrincipal.UpdateServicePrincipal
requestBody:
description: New property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.servicePrincipal'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.servicePrincipal'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- servicePrincipals.servicePrincipal
summary: Microsoft Graph Delete servicePrincipal
description: Delete a servicePrincipal object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/serviceprincipal-delete?view=graph-rest-1.0
operationId: servicePrincipals.servicePrincipal.DeleteServicePrincipal
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: servicePrincipal-id
in: path
description: The unique identifier of servicePrincipal
required: true
schema:
type: string
x-ms-docs-key-type: servicePrincipal
/servicePrincipals/{servicePrincipal-id}/appManagementPolicies:
description: >-
Provides operations to manage the appManagementPolicies property of the
microsoft.graph.servicePrincipal entity.
get:
tags:
- servicePrincipals.appManagementPolicy
summary: Microsoft Graph Get appManagementPolicies from servicePrincipals
description: The appManagementPolicy applied to this application.
operationId: servicePrincipals.ListAppManagementPolicies
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.appManagementPolicyCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
parameters:
- name: servicePrincipal-id
in: path
description: The unique identifier of servicePrincipal
required: true
schema:
type: string
x-ms-docs-key-type: servicePrincipal
/servicePrincipals/{servicePrincipal-id}/appManagementPolicies/{appManagementPolicy-id}:
description: >-
Provides operations to manage the appManagementPolicies property of the
microsoft.graph.servicePrincipal entity.
get:
tags:
- servicePrincipals.appManagementPolicy
summary: Microsoft Graph Get appManagementPolicies from servicePrincipals
description: The appManagementPolicy applied to this application.
operationId: servicePrincipals.GetAppManagementPolicies
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.appManagementPolicy'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: servicePrincipal-id
in: path
description: The unique identifier of servicePrincipal
required: true
schema:
type: string
x-ms-docs-key-type: servicePrincipal
- name: appManagementPolicy-id
in: path
description: The unique identifier of appManagementPolicy
required: true
schema:
type: string
x-ms-docs-key-type: appManagementPolicy
/servicePrincipals/{servicePrincipal-id}/appManagementPolicies/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- servicePrincipals.appManagementPolicy
summary: Microsoft Graph Get the number of the resource
operationId: servicePrincipals.appManagementPolicies.GetCount-5cee
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: servicePrincipal-id
in: path
description: The unique identifier of servicePrincipal
required: true
schema:
type: string
x-ms-docs-key-type: servicePrincipal
/servicePrincipals/{servicePrincipal-id}/appRoleAssignedTo:
description: >-
Provides operations to manage the appRoleAssignedTo property of the
microsoft.graph.servicePrincipal entity.
get:
tags:
- servicePrincipals.appRoleAssignment
summary: Microsoft Graph Get appRoleAssignment
description: Read the properties and relationships of an appRoleAssignment object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/serviceprincipal-list-approleassignedto?view=graph-rest-1.0
operationId: servicePrincipals.ListAppRoleAssignedTo
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.appRoleAssignmentCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- servicePrincipals.appRoleAssignment
summary: Microsoft Graph Grant an appRoleAssignment for a service principal
description: >-
Assign an app role for a resource service principal, to a user, group,
or client service principal. App roles that are assigned to service
principals are also known as application permissions. Application
permissions can be granted directly with app role assignments, or
through a consent experience. To grant an app role assignment, you need
three identifiers:
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/serviceprincipal-post-approleassignedto?view=graph-rest-1.0
operationId: servicePrincipals.CreateAppRoleAssignedTo
requestBody:
description: New navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.appRoleAssignment'
required: true
responses:
2XX:
description: Created navigation property.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.appRoleAssignment'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: servicePrincipal-id
in: path
description: The unique identifier of servicePrincipal
required: true
schema:
type: string
x-ms-docs-key-type: servicePrincipal
/servicePrincipals/{servicePrincipal-id}/appRoleAssignedTo/{appRoleAssignment-id}:
description: >-
Provides operations to manage the appRoleAssignedTo property of the
microsoft.graph.servicePrincipal entity.
get:
tags:
- servicePrincipals.appRoleAssignment
summary: Microsoft Graph Get appRoleAssignment
description: Read the properties and relationships of an appRoleAssignment object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/approleassignment-get?view=graph-rest-1.0
operationId: servicePrincipals.GetAppRoleAssignedTo
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.appRoleAssignment'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- servicePrincipals.appRoleAssignment
summary: Microsoft Graph Update the navigation property appRoleAssignedTo in servicePrincipals
operationId: servicePrincipals.UpdateAppRoleAssignedTo
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.appRoleAssignment'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.appRoleAssignment'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- servicePrincipals.appRoleAssignment
summary: Microsoft Graph Delete appRoleAssignedTo
description: >-
Deletes an appRoleAssignment that a user, group, or client service
principal has been granted for a resource service principal.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/serviceprincipal-delete-approleassignedto?view=graph-rest-1.0
operationId: servicePrincipals.DeleteAppRoleAssignedTo
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: servicePrincipal-id
in: path
description: The unique identifier of servicePrincipal
required: true
schema:
type: string
x-ms-docs-key-type: servicePrincipal
- name: appRoleAssignment-id
in: path
description: The unique identifier of appRoleAssignment
required: true
schema:
type: string
x-ms-docs-key-type: appRoleAssignment
/servicePrincipals/{servicePrincipal-id}/appRoleAssignedTo/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- servicePrincipals.appRoleAssignment
summary: Microsoft Graph Get the number of the resource
operationId: servicePrincipals.appRoleAssignedTo.GetCount-705c
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: servicePrincipal-id
in: path
description: The unique identifier of servicePrincipal
required: true
schema:
type: string
x-ms-docs-key-type: servicePrincipal
/servicePrincipals/{servicePrincipal-id}/appRoleAssignments:
description: >-
Provides operations to manage the appRoleAssignments property of the
microsoft.graph.servicePrincipal entity.
get:
tags:
- servicePrincipals.appRoleAssignment
summary: Microsoft Graph Get appRoleAssignment
description: Read the properties and relationships of an appRoleAssignment object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/serviceprincipal-list-approleassignments?view=graph-rest-1.0
operationId: servicePrincipals.ListAppRoleAssignments
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.appRoleAssignmentCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- servicePrincipals.appRoleAssignment
summary: Microsoft Graph Grant an appRoleAssignment to a service principal
description: >-
Assign an app role to a client service principal. App roles that are
assigned to service principals are also known as application
permissions. Application permissions can be granted directly with app
role assignments, or through a consent experience. To grant an app role
assignment to a client service principal, you need three identifiers:
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/serviceprincipal-post-approleassignments?view=graph-rest-1.0
operationId: servicePrincipals.CreateAppRoleAssignments
requestBody:
description: New navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.appRoleAssignment'
required: true
responses:
2XX:
description: Created navigation property.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.appRoleAssignment'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: servicePrincipal-id
in: path
description: The unique identifier of servicePrincipal
required: true
schema:
type: string
x-ms-docs-key-type: servicePrincipal
/servicePrincipals/{servicePrincipal-id}/appRoleAssignments/{appRoleAssignment-id}:
description: >-
Provides operations to manage the appRoleAssignments property of the
microsoft.graph.servicePrincipal entity.
get:
tags:
- servicePrincipals.appRoleAssignment
summary: Microsoft Graph Get appRoleAssignment
description: Read the properties and relationships of an appRoleAssignment object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/approleassignment-get?view=graph-rest-1.0
operationId: servicePrincipals.GetAppRoleAssignments
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.appRoleAssignment'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- servicePrincipals.appRoleAssignment
summary: Microsoft Graph Update the navigation property appRoleAssignments in servicePrincipals
operationId: servicePrincipals.UpdateAppRoleAssignments
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.appRoleAssignment'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.appRoleAssignment'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- servicePrincipals.appRoleAssignment
summary: Microsoft Graph Delete appRoleAssignment
description: >-
Deletes an appRoleAssignment that a service principal has been granted.
App roles which are assigned to service principals are also known as
application permissions. Deleting an app role assignment for a service
principal is equivalent to revoking the app-only permission grant.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/serviceprincipal-delete-approleassignments?view=graph-rest-1.0
operationId: servicePrincipals.DeleteAppRoleAssignments
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: servicePrincipal-id
in: path
description: The unique identifier of servicePrincipal
required: true
schema:
type: string
x-ms-docs-key-type: servicePrincipal
- name: appRoleAssignment-id
in: path
description: The unique identifier of appRoleAssignment
required: true
schema:
type: string
x-ms-docs-key-type: appRoleAssignment
/servicePrincipals/{servicePrincipal-id}/appRoleAssignments/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- servicePrincipals.appRoleAssignment
summary: Microsoft Graph Get the number of the resource
operationId: servicePrincipals.appRoleAssignments.GetCount-4e95
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: servicePrincipal-id
in: path
description: The unique identifier of servicePrincipal
required: true
schema:
type: string
x-ms-docs-key-type: servicePrincipal
/servicePrincipals/{servicePrincipal-id}/claimsMappingPolicies:
description: >-
Provides operations to manage the claimsMappingPolicies property of the
microsoft.graph.servicePrincipal entity.
get:
tags:
- servicePrincipals.claimsMappingPolicy
summary: Microsoft Graph List assigned claimsMappingPolicy
description: >-
List the claimsMappingPolicy objects that are assigned to a
servicePrincipal.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/serviceprincipal-list-claimsmappingpolicies?view=graph-rest-1.0
operationId: servicePrincipals.ListClaimsMappingPolicies
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.claimsMappingPolicyCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
parameters:
- name: servicePrincipal-id
in: path
description: The unique identifier of servicePrincipal
required: true
schema:
type: string
x-ms-docs-key-type: servicePrincipa
# --- truncated at 32 KB (523 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-graph/refs/heads/main/openapi/serviceprincipals-openapi-original.yml