Get servicePrincipal

Article
03/15/2024

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

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.

This method supports the $count, $expand, $filter, $orderby, $search, $select, and $top OData query parameters to help customize the response. Some queries are supported only when you use the ConsistencyLevel header set to eventual and $count. For more information, see Advanced query capabilities on directory objects.

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.

Request headers

Name	Description
Authorization	Bearer {token}. Required. Learn more about authentication and authorization.
Accept-Language	Language code. Optional.

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: Get the properties of the specified service principal

Request

The following example shows a request.

GET https://graph.microsoft.com/beta/servicePrincipals/{id}


// 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();

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



mgc-beta service-principals get --service-principal-id {servicePrincipal-id}

Important

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 $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-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)

Important

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();

Important

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}')
	.version('beta')
	.get();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\Beta\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->get()->wait();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Applications

Get-MgBetaServicePrincipal -ServicePrincipalId $servicePrincipalId

Important

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_beta 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()

Important

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

{
        "id": "59e617e5-e447-4adc-8b88-00af644d7c92",
        "deletedDateTime": null,
        "accountEnabled": true,
        "appDisplayName": "My App",
        "appId": "65415bb1-9267-4313-bbf5-ae259732ee12",
        "applicationTemplateId": null,
        "appOwnerOrganizationId": "1bc1c026-2f7b-48a5-98da-afa2fd8bc7bc",
        "appRoleAssignmentRequired": false,
        "disabledByMicrosoftStatus": null,
        "displayName": "foo",
        "errorUrl": null,
        "homepage": null,
        "loginUrl": null,
        "logoutUrl": null,
        "notificationEmailAddresses": [],
        "preferredSingleSignOnMode": null,
        "preferredTokenSigningKeyEndDateTime": null,
        "preferredTokenSigningKeyThumbprint": null,
        "publisherName": "Contoso",
        "replyUrls": [],
        "samlMetadataUrl": null,
        "samlSingleSignOnSettings": null,
        "servicePrincipalNames": [
            "f1bd758f-4a1a-4b71-aa20-a248a22a8928"
        ],
        "signInAudience": "AzureADandPersonalMicrosoftAccount",
        "tags": [],
        "verifiedPublisher": {
            "displayName": "publisher_contoso",
            "verifiedPublisherId": "9999999",
             "addedDateTime": "2021-04-24T17:49:44Z"
        },
        "addIns": [],
        "api": {
            "resourceSpecificApplicationPermissions": []
        },
        "appRoles": [],
        "info": {
            "termsOfServiceUrl": null,
            "supportUrl": null,
            "privacyStatementUrl": null,
            "marketingUrl": null,
            "logoUrl": null
        },
        "keyCredentials": [],
        "publishedPermissionScopes": [],
        "passwordCredentials": []
}

Example 2: Retrieve a service principal by its appId and only specific properties

Request

The following example shows a request.

GET https://graph.microsoft.com/beta/servicePrincipals(appId='00000003-0000-0000-c000-000000000000')?$select=id,appId,displayName,appRoles,publishedPermissionScopes,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.ServicePrincipalsWithAppId("{appId}").GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "id","appId","displayName","appRoles","publishedPermissionScopes","resourceSpecificApplicationPermissions" };
});

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



mgc-beta service-principals-with-app-id get --app-id {app-id} --select "id,appId,displayName,appRoles,publishedPermissionScopes,resourceSpecificApplicationPermissions"

Important

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 $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphserviceprincipalswithappid "github.com/microsoftgraph/msgraph-beta-sdk-go/serviceprincipalswithappid"
	  //other-imports
)

requestParameters := &graphserviceprincipalswithappid.ServicePrincipalsWithAppIdRequestBuilderGetQueryParameters{
	Select: [] string {"id","appId","displayName","appRoles","publishedPermissionScopes","resourceSpecificApplicationPermissions"},
}
configuration := &graphserviceprincipalswithappid.ServicePrincipalsWithAppIdRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
appId := "{appId}"
servicePrincipals, err := graphClient.ServicePrincipalsWithAppId(&appId).Get(context.Background(), configuration)

Important

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.servicePrincipalsWithAppId("{appId}").get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"id", "appId", "displayName", "appRoles", "publishedPermissionScopes", "resourceSpecificApplicationPermissions"};
});

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Snippet not available

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\ServicePrincipals_with_app_id\ServicePrincipalsWithAppIdRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new ServicePrincipalsWithAppIdRequestBuilderGetRequestConfiguration();
$queryParameters = ServicePrincipalsWithAppIdRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["id","appId","displayName","appRoles","publishedPermissionScopes","resourceSpecificApplicationPermissions"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->servicePrincipalsWithAppId('{appId}', )->get($requestConfiguration)->wait();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Applications

Get-MgBetaServicePrincipalByAppId -Property "id,appId,displayName,appRoles,publishedPermissionScopes,resourceSpecificApplicationPermissions"

Important

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_beta import GraphServiceClient
from msgraph_beta.generated.service_principals_with_app_id.service_principals_with_app_id_request_builder import ServicePrincipalsWithAppIdRequestBuilder
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 = ServicePrincipalsWithAppIdRequestBuilder.ServicePrincipalsWithAppIdRequestBuilderGetQueryParameters(
		select = ["id","appId","displayName","appRoles","publishedPermissionScopes","resourceSpecificApplicationPermissions"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.service_principals_with_app_id("{appId}").get(request_configuration = request_configuration)

Important

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"
        }
    ],
    "publishedPermissionScopes": [
        {
            "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

GET https://graph.microsoft.com/beta/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" };
});

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



mgc-beta service-principals get --service-principal-id {servicePrincipal-id} --select "customSecurityAttributes"

Important

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 $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphserviceprincipals "github.com/microsoftgraph/msgraph-beta-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)

Important

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"};
});

Important

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}')
	.version('beta')
	.select('customSecurityAttributes')
	.get();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\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();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Applications

Get-MgBetaServicePrincipal -ServicePrincipalId $servicePrincipalId -Property "customSecurityAttributes"

Important

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_beta import GraphServiceClient
from msgraph_beta.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)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$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/beta/$metadata#servicePrincipals(customSecurityAttributes)/$entity",
    "customSecurityAttributes": null
}

Share via

Get servicePrincipal

Permissions

HTTP request

Optional query parameters

Request headers

Request body

Response

Examples

Example 1: Get the properties of the specified service principal

Request

Response

Example 2: Retrieve a service principal by its appId and only specific properties

Request

Response

Example 3: Get the custom security attribute assignments of the specified service principal

Request

Response

Feedback

Additional resources