User Entitlements - Update User Entitlements

Service:: Member Entitlement Management

API Version:: 7.1

Edit the entitlements (License, Extensions, Projects, Teams etc) for one or more users.

PATCH https://vsaex.dev.azure.com/{organization}/_apis/userentitlements?api-version=7.1

With optional parameters:

PATCH https://vsaex.dev.azure.com/{organization}/_apis/userentitlements?doNotSendInviteForNewUsers={doNotSendInviteForNewUsers}&api-version=7.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' to use this version of the api.
doNotSendInviteForNewUsers	query		boolean	Whether to send email invites to new users or not

Request Body

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

Name	Type	Description
from	string	The path to copy from for the Move/Copy operation.
op	Operation	The patch operation
path	string	The path for the operation. In the case of an array, a zero based index can be used to specify the position in the array (e.g. /biscuits/0/name). The "-" character can be used instead of an index to insert at the end of the array (e.g. /biscuits/-).
value	object	The value for the operation. This is either a primitive or a JToken.

Responses

Name	Type	Description
200 OK	UserEntitlementOperationReference	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

PATCH https://vsaex.dev.azure.com/{organization}/_apis/userentitlements?api-version=7.1

[
  {
    "from": "",
    "op": "replace",
    "path": "/62707782-484a-4965-897a-50d2828a6510/accessLevel",
    "value": {
      "accountLicenseType": "express",
      "licensingSource": "account"
    }
  },
  {
    "from": "",
    "op": "replace",
    "path": "/df8d33a1-3039-4d20-b45a-7c93ab1288aa/accessLevel",
    "value": {
      "accountLicenseType": "express",
      "licensingSource": "account"
    }
  },
  {
    "from": "",
    "op": "remove",
    "path": "/df8d33a1-3039-4d20-b45a-7c93ab1288aa/projectEntitlements/2e77ca01-f341-461b-94b9-c774d1ed3927",
    "value": ""
  },
  {
    "from": "",
    "op": "add",
    "path": "/df8d33a1-3039-4d20-b45a-7c93ab1288aa/extensions",
    "value": {
      "id": "ms.feed"
    }
  }
]

Sample response

Status code:: 200

{
  "id": "7b0b98fe-e874-4d92-a921-96a779c6ecdc",
  "status": "succeeded",
  "haveResultsSucceeded": true,
  "completed": true,
  "results": [
    {
      "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": "df8d33a1-3039-4d20-b45a-7c93ab1288aa",
      "result": {
        "id": "df8d33a1-3039-4d20-b45a-7c93ab1288aa",
        "user": {
          "subjectKind": "user",
          "metaType": "member",
          "domain": "14c5367e-ee12-4c94-98b8-b52c1fe3cfb1",
          "principalName": "user2@fabrikam.com",
          "mailAddress": "user2@fabrikam.com",
          "origin": "aad",
          "originId": "00000000-0000-0000-0000-000000000000",
          "displayName": "User 2",
          "_links": {
            "self": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/users/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
            },
            "memberships": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/memberships/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
            },
            "membershipState": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/membershipstates/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
            },
            "storageKey": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/storagekeys/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
            }
          },
          "url": "https://vssps.dev.azure.com/fabrikam/_apis/graph/users/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN",
          "descriptor": "aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
        },
        "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": "df8d33a1-3039-4d20-b45a-7c93ab1288aa",
      "result": {
        "id": "df8d33a1-3039-4d20-b45a-7c93ab1288aa",
        "user": {
          "subjectKind": "user",
          "metaType": "member",
          "domain": "14c5367e-ee12-4c94-98b8-b52c1fe3cfb1",
          "principalName": "user2@fabrikam.com",
          "mailAddress": "user2@fabrikam.com",
          "origin": "aad",
          "originId": "00000000-0000-0000-0000-000000000000",
          "displayName": "User 2",
          "_links": {
            "self": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/users/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
            },
            "memberships": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/memberships/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
            },
            "membershipState": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/membershipstates/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
            },
            "storageKey": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/storagekeys/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
            }
          },
          "url": "https://vssps.dev.azure.com/fabrikam/_apis/graph/users/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN",
          "descriptor": "aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
        },
        "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": "df8d33a1-3039-4d20-b45a-7c93ab1288aa",
      "result": {
        "id": "df8d33a1-3039-4d20-b45a-7c93ab1288aa",
        "user": {
          "subjectKind": "user",
          "metaType": "member",
          "domain": "14c5367e-ee12-4c94-98b8-b52c1fe3cfb1",
          "principalName": "user2@fabrikam.com",
          "mailAddress": "user2@fabrikam.com",
          "origin": "aad",
          "originId": "00000000-0000-0000-0000-000000000000",
          "displayName": "User 2",
          "_links": {
            "self": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/users/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
            },
            "memberships": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/memberships/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
            },
            "membershipState": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/membershipstates/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
            },
            "storageKey": {
              "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/storagekeys/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
            }
          },
          "url": "https://vssps.dev.azure.com/fabrikam/_apis/graph/users/aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN",
          "descriptor": "aad.4QTZxY2YllTZ0YWNtETZmFWLlFjN30SOjRmNtY2M1QzN4MmN"
        },
        "accessLevel": {
          "licensingSource": "account",
          "accountLicenseType": "stakeholder",
          "msdnLicenseType": "none",
          "licenseDisplayName": "Stakeholder",
          "status": "active",
          "statusMessage": "",
          "assignmentSource": "unknown"
        },
        "lastAccessedDate": "0001-01-01T00:00:00Z",
        "projectEntitlements": [],
        "extensions": [],
        "groupAssignments": []
      }
    }
  ]
}

Definitions

Name	Description
JsonPatchDocument	The JSON model for JSON Patch Operations
Operation	The patch operation
OperationStatus	The current status of the operation.
UserEntitlementOperationReference
UserEntitlementOperationResult

JsonPatchDocument

Object

The JSON model for JSON Patch Operations

Name	Type	Description
from	string	The path to copy from for the Move/Copy operation.
op	Operation	The patch operation
path	string	The path for the operation. In the case of an array, a zero based index can be used to specify the position in the array (e.g. /biscuits/0/name). The "-" character can be used instead of an index to insert at the end of the array (e.g. /biscuits/-).
value	object	The value for the operation. This is either a primitive or a JToken.

Operation

Enumeration

The patch operation

Value	Description
add
copy
move
remove
replace
test

OperationStatus

Enumeration

The current status of the operation.

Value	Description
cancelled	The operation was cancelled by the user.
failed	The operation completed with a failure.
inProgress	The operation is in progress.
notSet	The operation does not have a status set.
queued	The operation has been queued.
succeeded	The operation completed successfully.

UserEntitlementOperationReference

Object

Name	Type	Description
completed	boolean	Operation completed with success or failure.
haveResultsSucceeded	boolean	True if all operations were successful.
id	string (uuid)	Unique identifier for the operation.
pluginId	string (uuid)	Unique identifier for the plugin.
results	UserEntitlementOperationResult[]	List of results for each operation.
status	OperationStatus	The current status of the operation.
url	string	URL to get the full operation object.

UserEntitlementOperationResult

Object

Name	Type	Description
errors	object[]	List of error codes paired with their corresponding error messages.
isSuccess	boolean	Success status of the operation.
result	string (T)	Resulting entitlement property. For specific implementations, see also: <seealso cref="T:Microsoft.VisualStudio.Services.MemberEntitlementManagement.WebApi.ServicePrincipalEntitlementOperationResult" /><seealso cref="T:Microsoft.VisualStudio.Services.MemberEntitlementManagement.WebApi.UserEntitlementOperationResult" />
userId	string (uuid)	Identifier of the Member being acted upon.

Share via

User Entitlements - Update User Entitlements

URI Parameters

Request Body

Responses

Security

oauth2

Scopes

Examples

Sample request

Sample response

Definitions

JsonPatchDocument

Operation

OperationStatus

UserEntitlementOperationReference

UserEntitlementOperationResult