Service Principal Entitlements - Add

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

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

{
  "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.

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.

ServicePrincipalEntitlement

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.

ServicePrincipalEntitlementOperationResult

Name Type Description
errors

object[]

List of error codes paired with their corresponding error messages.

isSuccess

boolean

Success status of the operation.

result

string

Resulting entitlement property. For specific implementations, see also:

servicePrincipalId

string

Identifier of the ServicePrincipal being acted upon.

ServicePrincipalEntitlementsPostResponse

Name Type Description
isSuccess

boolean

operationResult

ServicePrincipalEntitlementOperationResult

servicePrincipalEntitlement

ServicePrincipalEntitlement

TeamRef

A reference to a team

Name Type Description
id

string

Team ID

name

string

Team Name

UserEntitlement

A user entity with additional properties including their license, extensions, and project membership

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.

user

GraphUser

User reference.