User Entitlements - Update User Entitlement

Edit the entitlements (License, Extensions, Projects, Teams etc) for a user.

PATCH https://vsaex.dev.azure.com/{organization}/_apis/userentitlements/{userId}?api-version=5.0-preview.2

URI Parameters

Name In Required Type Description
organization
path True
  • string

The name of the Azure DevOps organization.

userId
path True
  • string
uuid

ID of the user.

api-version
query True
  • string

Version of the API to use. This should be set to '5.0-preview.2' to use this version of the api.

Request Body

Media Types: "application/json-patch+json"

Name Type Description
from
  • string

The path to copy from for the Move/Copy operation.

op

The patch operation

path
  • string

The path for the operation

value
  • object

The value for the operation. This is either a primitive or a JToken.

Responses

Name Type Description
200 OK

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

PATCH https://vsaex.dev.azure.com/{organization}/_apis/userentitlements/62707782-484a-4965-897a-50d2828a6510?api-version=5.0-preview.2
[
  {
    "from": "",
    "op": "replace",
    "path": "/accessLevel",
    "value": {
      "accountLicenseType": "express",
      "licensingSource": "account"
    }
  },
  {
    "from": "",
    "op": "remove",
    "path": "/projectEntitlements/2e77ca01-f341-461b-94b9-c774d1ed3927",
    "value": ""
  },
  {
    "from": "",
    "op": "add",
    "path": "/extensions",
    "value": {
      "id": "ms.feed"
    }
  }
]

Sample Response

{
  "operationResults": [
    {
      "isSuccess": true,
      "errors": [],
      "userId": "62707782-484a-4965-897a-50d2828a6510",
      "result": {
        "id": "62707782-484a-4965-897a-50d2828a6510",
        "user": {
          "subjectKind": "user",
          "metaType": "member",
          "domain": "14c5367e-ee12-4c94-98b8-b52c1fe3cfb1",
          "principalName": "user1@fabrikam.com",
          "mailAddress": "user1@fabrikam.com",
          "origin": "aad",
          "originId": "00000000-0000-0000-0000-000000000000",
          "displayName": "User 1",
          "_links": {
            "self": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/users/aad.wUGM3IDZ1UTZzczNtkTZmJWLiRzY30yNyE2MtcDNmFTOzMjY"
            },
            "memberships": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/memberships/aad.wUGM3IDZ1UTZzczNtkTZmJWLiRzY30yNyE2MtcDNmFTOzMjY"
            },
            "membershipState": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/membershipstates/aad.wUGM3IDZ1UTZzczNtkTZmJWLiRzY30yNyE2MtcDNmFTOzMjY"
            },
            "storageKey": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/storagekeys/aad.wUGM3IDZ1UTZzczNtkTZmJWLiRzY30yNyE2MtcDNmFTOzMjY"
            }
          },
          "url": "https://vssps.dev.azure.com/fabrikam/_apis/graph/users/aad.wUGM3IDZ1UTZzczNtkTZmJWLiRzY30yNyE2MtcDNmFTOzMjY",
          "descriptor": "aad.wUGM3IDZ1UTZzczNtkTZmJWLiRzY30yNyE2MtcDNmFTOzMjY"
        },
        "accessLevel": {
          "licensingSource": "account",
          "accountLicenseType": "stakeholder",
          "msdnLicenseType": "none",
          "licenseDisplayName": "Stakeholder",
          "status": "active",
          "statusMessage": "",
          "assignmentSource": "unknown"
        },
        "lastAccessedDate": "0001-01-01T00:00:00Z",
        "projectEntitlements": [],
        "extensions": [],
        "groupAssignments": []
      }
    },
    {
      "isSuccess": true,
      "errors": [],
      "userId": "08bbffa9-4944-4a98-b0c0-1fa718d5de3d",
      "result": null
    }
  ],
  "isSuccess": true,
  "userEntitlement": {
    "id": "62707782-484a-4965-897a-50d2828a6510",
    "user": {
      "subjectKind": "user",
      "metaType": "member",
      "domain": "14c5367e-ee12-4c94-98b8-b52c1fe3cfb1",
      "principalName": "user1@fabrikam.com",
      "mailAddress": "user1@fabrikam.com",
      "origin": "aad",
      "originId": "00000000-0000-0000-0000-000000000000",
      "displayName": "User 1",
      "_links": {
        "self": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/users/aad.wUGM3IDZ1UTZzczNtkTZmJWLiRzY30yNyE2MtcDNmFTOzMjY"
        },
        "memberships": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/memberships/aad.wUGM3IDZ1UTZzczNtkTZmJWLiRzY30yNyE2MtcDNmFTOzMjY"
        },
        "membershipState": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/membershipstates/aad.wUGM3IDZ1UTZzczNtkTZmJWLiRzY30yNyE2MtcDNmFTOzMjY"
        },
        "storageKey": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/storagekeys/aad.wUGM3IDZ1UTZzczNtkTZmJWLiRzY30yNyE2MtcDNmFTOzMjY"
        }
      },
      "url": "https://vssps.dev.azure.com/fabrikam/_apis/graph/users/aad.wUGM3IDZ1UTZzczNtkTZmJWLiRzY30yNyE2MtcDNmFTOzMjY",
      "descriptor": "aad.wUGM3IDZ1UTZzczNtkTZmJWLiRzY30yNyE2MtcDNmFTOzMjY"
    },
    "accessLevel": {
      "licensingSource": "account",
      "accountLicenseType": "stakeholder",
      "msdnLicenseType": "none",
      "licenseDisplayName": "Stakeholder",
      "status": "active",
      "statusMessage": "",
      "assignmentSource": "unknown"
    },
    "lastAccessedDate": "0001-01-01T00:00:00Z",
    "projectEntitlements": [],
    "extensions": [],
    "groupAssignments": []
  }
}

Definitions

AccessLevel
AccountLicenseType

Type of Account License (e.g. Express, Stakeholder etc.)

AccountUserStatus

User status in the account

AssignmentSource

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

Extension
GraphGroup

Graph group entity

GraphUser

Graph user entity

Group
GroupEntitlement
GroupLicensingRuleStatus

The status of the group rule.

GroupType

Group Type

JsonPatchDocument

The JSON model for JSON Patch Operations

LicensingSource

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

MsdnLicenseType

Type of MSDN License (e.g. Visual Studio Professional, Visual Studio Enterprise etc.)

Operation

The patch operation

ProjectEntitlement
ProjectRef
ReferenceLinks

The class to represent a collection of REST reference links.

TeamRef
UserEntitlement
UserEntitlementOperationResult
UserEntitlementsPatchResponse

AccessLevel

Name Type Description
accountLicenseType

Type of Account License (e.g. Express, Stakeholder etc.)

assignmentSource

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

licenseDisplayName
  • string

Display name of the License

licensingSource

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

msdnLicenseType

Type of MSDN License (e.g. Visual Studio Professional, Visual Studio Enterprise etc.)

status

User status in the account

statusMessage
  • string

Status message.

AccountLicenseType

Type of Account License (e.g. Express, Stakeholder etc.)

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

Extension

Name Type Description
assignmentSource

Assignment source for this extension. I.e. explicitly assigned or from a group rule.

id
  • string

Gallery Id of the Extension.

name
  • string

Friendly name of this extension.

source

Source of this extension assignment. Ex: msdn, account, none, etc.

GraphGroup

Graph group entity

Name Type Description
_links

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.

GraphUser

Graph user entity

Name Type Description
_links

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.

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

metadataUpdateDate
  • string
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

Name Type Description
displayName
  • string

Display Name of the Group

groupType

Group Type

GroupEntitlement

Name Type Description
extensionRules

Extension Rules.

group

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

License Rule.

members

Group members. Only used when creating a new group.

projectEntitlements

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

status

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

JsonPatchDocument

The JSON model for JSON Patch Operations

Name Type Description
from
  • string

The path to copy from for the Move/Copy operation.

op

The patch operation

path
  • string

The path for the operation

value
  • object

The value for the operation. This is either a primitive or a JToken.

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.)

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

Operation

The patch operation

Name Type Description
add
  • string
copy
  • string
move
  • string
remove
  • string
replace
  • string
test
  • string

ProjectEntitlement

Name Type Description
assignmentSource

Assignment Source (e.g. Group or Unknown).

group

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

isProjectPermissionInherited
  • boolean

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

projectRef

Project Ref

teamRefs

Team Ref.

ProjectRef

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.

TeamRef

Name Type Description
id
  • string

Team ID

name
  • string

Team Name

UserEntitlement

Name Type Description
accessLevel

User's access level denoted by a license.

extensions

User's extensions.

groupAssignments

[Readonly] GroupEntitlements that this user belongs to.

id
  • string

The unique identifier which matches the Id of the Identity associated with the GraphMember.

lastAccessedDate
  • string

[Readonly] Date the user last accessed the collection.

projectEntitlements

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

user

User reference.

UserEntitlementOperationResult

Name Type Description
errors
  • object[]

List of error codes paired with their corresponding error messages.

isSuccess
  • boolean

Success status of the operation.

result

Result of the MemberEntitlement after the operation.

userId
  • string

Identifier of the Member being acted upon.

UserEntitlementsPatchResponse

Name Type Description
isSuccess
  • boolean

True if all operations were successful.

operationResults

List of results for each operation.

userEntitlement

Result of the user entitlement after the operations have been applied.