Namespace: microsoft.graph
Retrieve the properties and relationships of a servicePrincipal object.
This API is available in the following national cloud deployments.
| Global service |
US Government L4 |
US Government L5 (DOD) |
China operated by 21Vianet |
| ✅ |
✅ |
✅ |
✅ |
Permissions
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
| Permission type |
Least privileged permissions |
Higher privileged permissions |
| Delegated (work or school account) |
Application.Read.All |
Application.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All |
| Delegated (personal Microsoft account) |
Not supported. |
Not supported. |
| Application |
Application.Read.All |
Application.ReadWrite.OwnedBy, Application.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All |
Note
- A service principal can retrieve its own application and service principal details without being granted any application permissions.
- The Application.ReadWrite.OwnedBy permission allows an app to call
GET /applications and GET /servicePrincipals to list all applications and service principals in the tenant. This scope of access has been allowed for the permission.
- To read the customSecurityAttributes property:
- In delegated scenarios, the admin must be assigned the Attribute Assignment Administrator role and the app granted the CustomSecAttributeAssignment.Read.All delegated permission.
- In app-only scenarios using Microsoft Graph permissions, the app must be granted the CustomSecAttributeAssignment.Reade.All application permission.
HTTP request
You can address the service principal using either its id or appId. id and appId are referred to as the Object ID and Application (Client) ID, respectively, in app registrations in the Microsoft Entra admin center.
GET /servicePrincipals/{id}
GET /servicePrincipals(appId='{appId}')
Optional query parameters
This method supports the $select and $expand OData query parameters to help customize the response.
By default, this API doesn't return the public key value of the key in the keyCredentials property unless keyCredentials is specified in a $select query.
For example, $select=id,appId,keyCredentials.
The use of $select to get keyCredentials for service principals has a throttling limit of 150 requests per minute for every tenant.
Providing the Accept-Language header with a supported language code, such as es-ES or de-DE, will return localized values where available. Note that the header is not supported for list operations.
Request body
Don't supply a request body for this method.
Response
If successful, this method returns a 200 OK response code and a servicePrincipal object in the response body.
Examples
Example 1: Retrieve a service principal by its ID
Request
The following example shows a request.
GET https://graph.microsoft.com/v1.0/servicePrincipals/00063ffc-54e9-405d-b8f3-56124728e051
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].GetAsync();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
//other-imports
)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Get(context.Background(), nil)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ServicePrincipal result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").get();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
const options = {
authProvider,
};
const client = Client.init(options);
let servicePrincipal = await client.api('/servicePrincipals/00063ffc-54e9-405d-b8f3-56124728e051')
.get();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->get()->wait();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').get()
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Response
The following example shows the response.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-type: application/json
{
"accountEnabled": true,
"addIns": [],
"alternativeNames": ["http://contoso/a7770d29-4321-41a6-b863-ca11d6639448"],
"appDisplayName": "My app",
"appId": "appId-value",
"appOwnerOrganizationId": "65415bb1-9267-4313-bbf5-ae259732ee12",
"appRoleAssignmentRequired":true,
"appRoles": [],
"disabledByMicrosoftStatus": null,
"displayName": "My app instance in tenant",
"endpoints": [],
"homepage": null,
"id": "00af5dfb-85da-4b41-a677-0c6b86dd34f8",
"verifiedPublisher": {
"displayName": "publisher_contoso",
"verifiedPublisherId": "9999999",
"addedDateTime": "2021-04-24T17:49:44Z"
},
"info": {
"termsOfServiceUrl": null,
"supportUrl": null,
"privacyStatementUrl": null,
"marketingUrl": null,
"logoUrl": null
},
"keyCredentials": [],
"logoutUrl": null,
"oauth2PermissionScopes": [],
"passwordCredentials": [],
"publisherName": null,
"replyUrls": [],
"resourceSpecificApplicationPermissions": [],
"servicePrincipalNames": [],
"servicePrincipalType": null,
"signInAudience": "AzureADandPersonalMicrosoftAccount",
"tags": [],
"tokenEncryptionKeyId": null
}
Example 2: Retrieve the specific properties of a service principal
Request
The following example shows a request.
GET https://graph.microsoft.com/v1.0/servicePrincipals/7408235b-7540-4850-82fe-a5f15ed019e2?$select=id,appId,displayName,appRoles,oauth2PermissionScopes,resourceSpecificApplicationPermissions
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "id","appId","displayName","appRoles","oauth2PermissionScopes","resourceSpecificApplicationPermissions" };
});
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
mgc service-principals get --service-principal-id {servicePrincipal-id} --select "id,appId,displayName,appRoles,oauth2PermissionScopes,resourceSpecificApplicationPermissions"
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphserviceprincipals "github.com/microsoftgraph/msgraph-sdk-go/serviceprincipals"
//other-imports
)
requestParameters := &graphserviceprincipals.ServicePrincipalItemRequestBuilderGetQueryParameters{
Select: [] string {"id","appId","displayName","appRoles","oauth2PermissionScopes","resourceSpecificApplicationPermissions"},
}
configuration := &graphserviceprincipals.ServicePrincipalItemRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Get(context.Background(), configuration)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ServicePrincipal result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"id", "appId", "displayName", "appRoles", "oauth2PermissionScopes", "resourceSpecificApplicationPermissions"};
});
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
const options = {
authProvider,
};
const client = Client.init(options);
let servicePrincipal = await client.api('/servicePrincipals/7408235b-7540-4850-82fe-a5f15ed019e2')
.select('id,appId,displayName,appRoles,oauth2PermissionScopes,resourceSpecificApplicationPermissions')
.get();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\ServicePrincipals\Item\ServicePrincipalItemRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new ServicePrincipalItemRequestBuilderGetRequestConfiguration();
$queryParameters = ServicePrincipalItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["id","appId","displayName","appRoles","oauth2PermissionScopes","resourceSpecificApplicationPermissions"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->get($requestConfiguration)->wait();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Import-Module Microsoft.Graph.Applications
Get-MgServicePrincipal -ServicePrincipalId $servicePrincipalId -Property "id,appId,displayName,appRoles,oauth2PermissionScopes,resourceSpecificApplicationPermissions"
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.service_principals.item.service_principal_item_request_builder import ServicePrincipalItemRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = ServicePrincipalItemRequestBuilder.ServicePrincipalItemRequestBuilderGetQueryParameters(
select = ["id","appId","displayName","appRoles","oauth2PermissionScopes","resourceSpecificApplicationPermissions"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').get(request_configuration = request_configuration)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Response
The following example shows the response.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals(id,appId,displayName,appRoles,publishedPermissionScopes)/$entity",
"id": "7408235b-7540-4850-82fe-a5f15ed019e2",
"appId": "00000003-0000-0000-c000-000000000000",
"displayName": "Microsoft Graph",
"appRoles": [
{
"allowedMemberTypes": [
"Application"
],
"description": "Allows the app to read all class assignments without grades for all users without a signed-in user.",
"displayName": "Read all class assignments without grades",
"id": "6e0a958b-b7fc-4348-b7c4-a6ab9fd3dd0e",
"isEnabled": true,
"origin": "Application",
"value": "EduAssignments.ReadBasic.All"
}
],
"oauth2PermissionScopes": [
{
"adminConsentDescription": "Allows the app to see your users' basic profile (e.g., name, picture, user name, email address)",
"adminConsentDisplayName": "View users' basic profile",
"id": "14dad69e-099b-42c9-810b-d002981feec1",
"isEnabled": true,
"type": "User",
"userConsentDescription": "Allows the app to see your basic profile (e.g., name, picture, user name, email address)",
"userConsentDisplayName": "View your basic profile",
"value": "profile"
}
]
}
Example 3: Get the custom security attribute assignments of the specified service principal
The following example gets the custom security attributes of the specified service principal.
Attribute #1
- Attribute set:
Engineering
- Attribute:
Project
- Attribute data type: Collection of Strings
- Attribute value:
["Baker","Cascade"]
Attribute #2
- Attribute set:
Engineering
- Attribute:
CostCenter
- Attribute data type: Collection of Integers
- Attribute value:
[1001]
Attribute #3
- Attribute set:
Engineering
- Attribute:
Certification
- Attribute data type: Boolean
- Attribute value:
true
Attribute #4
- Attribute set:
Marketing
- Attribute:
Level
- Attribute data type: String
- Attribute value:
"Public"
To get custom security attribute assignments, the calling principal must be assigned the Attribute Assignment Reader or Attribute Assignment Administrator role and must be granted the CustomSecAttributeAssignment.Read.All or CustomSecAttributeAssignment.ReadWrite.All permission.
Request
The following example shows a request.
GET https://graph.microsoft.com/v1.0/servicePrincipals/{id}?$select=customSecurityAttributes
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "customSecurityAttributes" };
});
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphserviceprincipals "github.com/microsoftgraph/msgraph-sdk-go/serviceprincipals"
//other-imports
)
requestParameters := &graphserviceprincipals.ServicePrincipalItemRequestBuilderGetQueryParameters{
Select: [] string {"customSecurityAttributes"},
}
configuration := &graphserviceprincipals.ServicePrincipalItemRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Get(context.Background(), configuration)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ServicePrincipal result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"customSecurityAttributes"};
});
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
const options = {
authProvider,
};
const client = Client.init(options);
let servicePrincipal = await client.api('/servicePrincipals/{id}')
.select('customSecurityAttributes')
.get();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\ServicePrincipals\Item\ServicePrincipalItemRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new ServicePrincipalItemRequestBuilderGetRequestConfiguration();
$queryParameters = ServicePrincipalItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["customSecurityAttributes"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->get($requestConfiguration)->wait();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Import-Module Microsoft.Graph.Applications
Get-MgServicePrincipal -ServicePrincipalId $servicePrincipalId -Property "customSecurityAttributes"
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.service_principals.item.service_principal_item_request_builder import ServicePrincipalItemRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = ServicePrincipalItemRequestBuilder.ServicePrincipalItemRequestBuilderGetQueryParameters(
select = ["customSecurityAttributes"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').get(request_configuration = request_configuration)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Response
The following example shows the response.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals(customSecurityAttributes)/$entity",
"customSecurityAttributes": {
"Engineering": {
"@odata.type": "#microsoft.graph.customSecurityAttributeValue",
"[email protected]": "#Collection(String)",
"Project": [
"Baker",
"Cascade"
],
"[email protected]": "#Collection(Int32)",
"CostCenter": [
1001
],
"Certification": true
},
"Marketing": {
"@odata.type": "#microsoft.graph.customSecurityAttributeValue",
"Level": "Public"
}
}
}
If there are no custom security attributes assigned to the service principal or if the calling principal does not have access, the response will look like:
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals(customSecurityAttributes)/$entity",
"customSecurityAttributes": null
}