Service Principal Entitlements - Add

Reference

Service:: Member Entitlement Management

API Version:: 7.1-preview.1

Add a service principal, assign license and extensions and make them a member of a project group in an account.

NOTE: If you are working with AAD app registration, you can find service principal of your app in enterprise applications, and make sure to use service principal's object id as originId parameter in the request body

POST https://vsaex.dev.azure.com/{organization}/_apis/serviceprincipalentitlements?api-version=7.1-preview.1

URI Parameters

Name	In	Required	Type	Description
organization	path	True	string	The name of the Azure DevOps organization.
api-version	query	True	string	Version of the API to use. This should be set to '7.1-preview.1' to use this version of the api.

Request Body

Name	Type	Description
accessLevel	AccessLevel	Member's access level denoted by a license.
dateCreated	string	[Readonly] Date the member was added to the collection.
groupAssignments	GroupEntitlement[]	[Readonly] GroupEntitlements that this member belongs to.
id	string	The unique identifier which matches the Id of the Identity associated with the GraphMember.
lastAccessedDate	string	[Readonly] Date the member last accessed the collection.
projectEntitlements	ProjectEntitlement[]	Relation between a project and the member's effective permissions in that project.
servicePrincipal	GraphServicePrincipal	ServicePrincipal reference.

Responses

Name	Type	Description
200 OK	ServicePrincipalEntitlementsPostResponse	successful operation

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name	Description
vso.memberentitlementmanagement_write	Grants the ability to manage users, their licenses as well as projects and extensions they can access

Examples

Sample request

HTTP

POST https://vsaex.dev.azure.com/{organization}/_apis/serviceprincipalentitlements?api-version=7.1-preview.1

{
  "accessLevel": {
    "accountLicenseType": "stakeholder"
  },
  "projectEntitlements": [
    {
      "group": {
        "groupType": "projectReader"
      },
      "projectRef": {
        "id": "c944c983-e90b-4499-938a-5897ea954ace"
      }
    }
  ],
  "servicePrincipal": {
    "origin": "aad",
    "originId": "92e26ce8-8e7c-4555-bdab-813b34b8e53a",
    "subjectKind": "servicePrincipal"
  }
}

Sample response

Status code:: 200

{
  "operationResult": {
    "servicePrincipalId": "b34cdbfd-1f2d-60c6-b04a-8a99d301a6cd",
    "isSuccess": true,
    "errors": [],
    "result": {
      "servicePrincipal": {
        "subjectKind": "servicePrincipal",
        "applicationId": "a9a6a563-c4c6-42cd-8bd6-90259e8f99f4",
        "metaType": "application",
        "directoryAlias": "92e26ce8-8e7c-4555-bdab-813b34b8e53a",
        "domain": "5e46c442-89f0-4452-b132-3336eaeec3fc",
        "principalName": "a9a6a563-c4c6-42cd-8bd6-90259e8f99f4",
        "mailAddress": null,
        "origin": "aad",
        "originId": "92e26ce8-8e7c-4555-bdab-813b34b8e53a",
        "displayName": "Service principal",
        "_links": {
          "self": {
            "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/ServicePrincipals/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
          },
          "memberships": {
            "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/Memberships/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
          },
          "membershipState": {
            "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/MembershipStates/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
          },
          "storageKey": {
            "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/StorageKeys/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
          },
          "avatar": {
            "href": "https://dev.azure.com/fabrikam/_apis/GraphProfile/MemberAvatars/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
          }
        },
        "url": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/ServicePrincipals/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk",
        "descriptor": "aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
      },
      "id": "b34cdbfd-1f2d-60c6-b04a-8a99d301a6cd",
      "accessLevel": {
        "licensingSource": "account",
        "accountLicenseType": "earlyAdopter",
        "msdnLicenseType": "none",
        "licenseDisplayName": "Early Adopter",
        "status": "pending",
        "statusMessage": "",
        "assignmentSource": "unknown"
      },
      "lastAccessedDate": "0001-01-01T00:00:00Z",
      "dateCreated": "2023-03-27T11:32:45.7401972Z",
      "projectEntitlements": [],
      "groupAssignments": []
    }
  },
  "isSuccess": true,
  "servicePrincipalEntitlement": {
    "servicePrincipal": {
      "subjectKind": "servicePrincipal",
      "applicationId": "a9a6a563-c4c6-42cd-8bd6-90259e8f99f4",
      "metaType": "application",
      "directoryAlias": "92e26ce8-8e7c-4555-bdab-813b34b8e53a",
      "domain": "5e46c442-89f0-4452-b132-3336eaeec3fc",
      "principalName": "a9a6a563-c4c6-42cd-8bd6-90259e8f99f4",
      "mailAddress": null,
      "origin": "aad",
      "originId": "92e26ce8-8e7c-4555-bdab-813b34b8e53a",
      "displayName": "Service principal",
      "_links": {
        "self": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/ServicePrincipals/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
        },
        "memberships": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/Memberships/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
        },
        "membershipState": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/MembershipStates/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
        },
        "storageKey": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/StorageKeys/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
        },
        "avatar": {
          "href": "https://dev.azure.com/fabrikam/_apis/GraphProfile/MemberAvatars/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
        }
      },
      "url": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/ServicePrincipals/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk",
      "descriptor": "aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
    },
    "id": "b34cdbfd-1f2d-60c6-b04a-8a99d301a6cd",
    "accessLevel": {
      "licensingSource": "account",
      "accountLicenseType": "earlyAdopter",
      "msdnLicenseType": "none",
      "licenseDisplayName": "Early Adopter",
      "status": "pending",
      "statusMessage": "",
      "assignmentSource": "unknown"
    },
    "lastAccessedDate": "0001-01-01T00:00:00Z",
    "dateCreated": "2023-03-27T11:32:45.7401972Z",
    "projectEntitlements": [],
    "groupAssignments": []
  }
}

Definitions

Name	Description
AccessLevel	License assigned to a user
AccountLicenseType	Type of Account License (e.g. Express, Stakeholder etc.). To use the AccountLicenseType, LicensingSource should be defined as 'account' in the request body.
AccountUserStatus	User status in the account
AssignmentSource	Assignment Source of the License (e.g. Group, Unknown etc.
GraphGroup	Graph group entity
GraphServicePrincipal
GraphUser
Group	Project Group (e.g. Contributor, Reader etc.)
GroupEntitlement	A group entity with additional properties including its license, extensions, and project membership
GroupLicensingRuleStatus	The status of the group rule.
GroupType	Group Type
LicensingSource	Licensing Source (e.g. Account. MSDN etc.)
MsdnLicenseType	Type of MSDN License (e.g. Visual Studio Professional, Visual Studio Enterprise etc.). To use the MsdnLicenseType, LicensingSource should be defined as 'msdn' in the request body.
ProjectEntitlement	Relation between a project and the user's effective permissions in that project.
ProjectPermissionInherited	Whether the user is inheriting permissions to a project through a Azure DevOps or AAD group membership.
ProjectRef	A reference to a project
ReferenceLinks	The class to represent a collection of REST reference links.
ServicePrincipalEntitlement
ServicePrincipalEntitlementOperationResult
ServicePrincipalEntitlementsPostResponse
TeamRef	A reference to a team
UserEntitlement	A user entity with additional properties including their license, extensions, and project membership

AccessLevel

License assigned to a user

Name	Type	Description
accountLicenseType	AccountLicenseType	Type of Account License (e.g. Express, Stakeholder etc.). To use the AccountLicenseType, LicensingSource should be defined as 'account' in the request body.
assignmentSource	AssignmentSource	Assignment Source of the License (e.g. Group, Unknown etc.
licenseDisplayName	string	Display name of the License
licensingSource	LicensingSource	Licensing Source (e.g. Account. MSDN etc.)
msdnLicenseType	MsdnLicenseType	Type of MSDN License (e.g. Visual Studio Professional, Visual Studio Enterprise etc.). To use the MsdnLicenseType, LicensingSource should be defined as 'msdn' in the request body.
status	AccountUserStatus	User status in the account
statusMessage	string	Status message.

AccountLicenseType

Type of Account License (e.g. Express, Stakeholder etc.). To use the AccountLicenseType, LicensingSource should be defined as 'account' in the request body.

Name	Type	Description
advanced	string
earlyAdopter	string
express	string
none	string
professional	string
stakeholder	string

AccountUserStatus

User status in the account

Name	Type	Description
active	string	User has signed in at least once to the VSTS account
deleted	string	User is removed from the VSTS account by the VSTS account admin
disabled	string	User cannot sign in; primarily used by admin to temporarily remove a user due to absence or license reallocation
expired	string	User can sign in; primarily used when license is in expired state and we give a grace period
none	string
pending	string	User is invited to join the VSTS account by the VSTS account admin, but has not signed up/signed in yet
pendingDisabled	string	User is disabled; if reenabled, they will still be in the Pending state

AssignmentSource

Assignment Source of the License (e.g. Group, Unknown etc.

Name	Type	Description
groupRule	string
none	string
unknown	string

GraphGroup

Graph group entity

Name	Type	Description
_links	ReferenceLinks	This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.
description	string	A short phrase to help human readers disambiguate groups with similar names
descriptor	string	The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations.
displayName	string	This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.
domain	string	This represents the name of the container of origin for a graph member. (For MSA this is "Windows Live ID", for AD the name of the domain, for AAD the tenantID of the directory, for VSTS groups the ScopeId, etc)
legacyDescriptor	string	[Internal Use Only] The legacy descriptor is here in case you need to access old version IMS using identity descriptor.
mailAddress	string	The email address of record for a given graph member. This may be different than the principal name.
origin	string	The type of source provider for the origin identifier (ex:AD, AAD, MSA)
originId	string	The unique identifier from the system of origin. Typically a sid, object id or Guid. Linking and unlinking operations can cause this value to change for a user because the user is not backed by a different provider and has a different unique id in the new provider.
principalName	string	This is the PrincipalName of this graph member from the source provider. The source provider may change this field over time and it is not guaranteed to be immutable for the life of the graph member by VSTS.
subjectKind	string	This field identifies the type of the graph subject (ex: Group, Scope, User).
url	string	This url is the full route to the source resource of this graph subject.

GraphServicePrincipal

Name	Type	Description
_links	ReferenceLinks	This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.
applicationId	string
descriptor	string	The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations.
directoryAlias	string	The short, generally unique name for the user in the backing directory. For AAD users, this corresponds to the mail nickname, which is often but not necessarily similar to the part of the user's mail address before the @ sign. For GitHub users, this corresponds to the GitHub user handle.
displayName	string	This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.
domain	string	This represents the name of the container of origin for a graph member. (For MSA this is "Windows Live ID", for AD the name of the domain, for AAD the tenantID of the directory, for VSTS groups the ScopeId, etc)
isDeletedInOrigin	boolean	When true, the group has been deleted in the identity provider
legacyDescriptor	string	[Internal Use Only] The legacy descriptor is here in case you need to access old version IMS using identity descriptor.
mailAddress	string	The email address of record for a given graph member. This may be different than the principal name.
metaType	string	The meta type of the user in the origin, such as "member", "guest", etc. See UserMetaType for the set of possible values.
origin	string	The type of source provider for the origin identifier (ex:AD, AAD, MSA)
originId	string	The unique identifier from the system of origin. Typically a sid, object id or Guid. Linking and unlinking operations can cause this value to change for a user because the user is not backed by a different provider and has a different unique id in the new provider.
principalName	string	This is the PrincipalName of this graph member from the source provider. The source provider may change this field over time and it is not guaranteed to be immutable for the life of the graph member by VSTS.
subjectKind	string	This field identifies the type of the graph subject (ex: Group, Scope, User).
url	string	This url is the full route to the source resource of this graph subject.

GraphUser

Name	Type	Description
_links	ReferenceLinks	This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.
descriptor	string	The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations.
directoryAlias	string	The short, generally unique name for the user in the backing directory. For AAD users, this corresponds to the mail nickname, which is often but not necessarily similar to the part of the user's mail address before the @ sign. For GitHub users, this corresponds to the GitHub user handle.
displayName	string	This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.
domain	string	This represents the name of the container of origin for a graph member. (For MSA this is "Windows Live ID", for AD the name of the domain, for AAD the tenantID of the directory, for VSTS groups the ScopeId, etc)
isDeletedInOrigin	boolean	When true, the group has been deleted in the identity provider
legacyDescriptor	string	[Internal Use Only] The legacy descriptor is here in case you need to access old version IMS using identity descriptor.
mailAddress	string	The email address of record for a given graph member. This may be different than the principal name.
metaType	string	The meta type of the user in the origin, such as "member", "guest", etc. See UserMetaType for the set of possible values.
origin	string	The type of source provider for the origin identifier (ex:AD, AAD, MSA)
originId	string	The unique identifier from the system of origin. Typically a sid, object id or Guid. Linking and unlinking operations can cause this value to change for a user because the user is not backed by a different provider and has a different unique id in the new provider.
principalName	string	This is the PrincipalName of this graph member from the source provider. The source provider may change this field over time and it is not guaranteed to be immutable for the life of the graph member by VSTS.
subjectKind	string	This field identifies the type of the graph subject (ex: Group, Scope, User).
url	string	This url is the full route to the source resource of this graph subject.

Group

Project Group (e.g. Contributor, Reader etc.)

Name	Type	Description
displayName	string	Display Name of the Group
groupType	GroupType	Group Type

GroupEntitlement

A group entity with additional properties including its license, extensions, and project membership

Name	Type	Description
group	GraphGroup	Member reference.
id	string	The unique identifier which matches the Id of the GraphMember.
lastExecuted	string	[Readonly] The last time the group licensing rule was executed (regardless of whether any changes were made).
licenseRule	AccessLevel	License Rule.
members	UserEntitlement[]	Group members. Only used when creating a new group.
projectEntitlements	ProjectEntitlement[]	Relation between a project and the member's effective permissions in that project.
status	GroupLicensingRuleStatus	The status of the group rule.

GroupLicensingRuleStatus

The status of the group rule.

Name	Type	Description
applied	string	Rule is applied
applyPending	string	Rule is created or updated, but apply is pending
incompatible	string	The group rule was incompatible
unableToApply	string	Rule failed to apply unexpectedly and should be retried

GroupType

Group Type

Name	Type	Description
custom	string
projectAdministrator	string
projectContributor	string
projectReader	string
projectStakeholder	string

LicensingSource

Licensing Source (e.g. Account. MSDN etc.)

Name	Type	Description
account	string
auto	string
msdn	string
none	string
profile	string
trial	string

MsdnLicenseType

Type of MSDN License (e.g. Visual Studio Professional, Visual Studio Enterprise etc.). To use the MsdnLicenseType, LicensingSource should be defined as 'msdn' in the request body.

Name	Type	Description
eligible	string
enterprise	string
none	string
platforms	string
premium	string
professional	string
testProfessional	string
ultimate	string

ProjectEntitlement

Relation between a project and the user's effective permissions in that project.

Name	Type	Description
assignmentSource	AssignmentSource	Assignment Source (e.g. Group or Unknown).
group	Group	Project Group (e.g. Contributor, Reader etc.)
projectPermissionInherited	ProjectPermissionInherited	Whether the user is inheriting permissions to a project through a Azure DevOps or AAD group membership.
projectRef	ProjectRef	Project Ref
teamRefs	TeamRef[]	Team Ref.

ProjectPermissionInherited

Whether the user is inheriting permissions to a project through a Azure DevOps or AAD group membership.

Name	Type	Description
inherited	string
notInherited	string
notSet	string

ProjectRef

A reference to a project

Name	Type	Description
id	string	Project ID.
name	string	Project Name.

ReferenceLinks

The class to represent a collection of REST reference links.

Name	Type	Description
links	object	The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.