User Entitlements - Get User Entitlements

Get a paged set of user entitlements matching the filter criteria. If no filter is is passed, a page from all the account users is returned.

GET https://vsaex.dev.azure.com/{organization}/_apis/userentitlements?api-version=5.1-preview.2
GET https://vsaex.dev.azure.com/{organization}/_apis/userentitlements?top={top}&skip={skip}&filter={filter}&sortOption={sortOption}&api-version=5.1-preview.2

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 '5.1-preview.2' to use this version of the api.

filter
query
  • string

Comma (",") separated list of properties and their values to filter on. Currently, the API only supports filtering by ExtensionId. An example parameter would be filter=extensionId eq search.

skip
query
  • integer
int32

Offset: Number of records to skip. Default value is 0

sortOption
query
  • string

PropertyName and Order (separated by a space ( )) to sort on (e.g. LastAccessDate Desc)

top
query
  • integer
int32

Maximum number of the user entitlements to return. Max value is 10000. Default value is 100

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 Grants the ability to read users, their licenses as well as projects and extensions they can access

Definitions

AccessLevel

License assigned to a user

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

An extension assigned to a user

GraphGroup

Graph group entity

GraphUser

Graph user entity

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

PagedGraphMemberList

A page of users

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.

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

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

An extension assigned to a user

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.

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

Group Type

GroupEntitlement

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

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

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

PagedGraphMemberList

A page of users

Name Type Description
members

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

ProjectEntitlement

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

Name Type Description
assignmentSource

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

group

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

projectPermissionInherited

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

projectRef

Project Ref

teamRefs

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.

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

User's access level denoted by a license.

dateCreated
  • string

[Readonly] Date the user was added to the collection.

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.