api-version = 4.0-preview
This API is an Alpha preview. We are eager to get customer feedback on data shape and usage patterns but the API is not yet ready for consumption in production scenarios.
The VSTS Graph API allows you to manage users, groups, and group memberships.
VSIDs uniquely identity a user or group within an account. They do not uniquely identify users or groups in cross-account scenarios. Descriptors uniquely identify users and groups across all accounts. This is a very important distinction because our consumers are demanding more and more features that require pleasant experiences across multiple accounts. Using VSIDs leads to confusion, strange errors, and incorrect or unexpected behavior.
Descriptors provide a much better experience for cross account user/group management. Over time, we will be changing guidance and APIs to support VSIDs only for storage of a unique identifier to a user or group. Descriptors will be used to reference the user/group for a running system.
We do not recommend persisting descriptors because there are several scenarios where they can change overtime: editing the user in the AAD backing store and linking/unlinking an account will result in the user getting a new descriptor.
Retrieving a descriptor from another identitifier
Some REST APIs, such as work item tracking or git, may reference return identifiers other than descriptors. We're working to change this long term but in the meantime, we offer a set of mechanisms to convert these identifiers to descriptors.
Storage Keys (previously known as VSIDs) are a GUID representation of a user or group that is unique in the scope of an account, but not across an organization. When storing information about a user, use the StorageKeys resource to translate the Descriptor returned by a given Graph API call into a Storage Key and store the resulting GUID. When retrieving data about a user, use the Descriptors resource to translate a storage key into a descriptor for use in subsequent Graph API calls.
UPN or Display Name
Often, identities are represented simply as display names such as Jamal Hartnett or UPNs such as firstname.lastname@example.org. These are not unique at any scope. Search is an resource that will take a text string and run a search across an account or project to find all potential matches. The more distinct the input, the better chance the resource will return a single result. The search resource will accept display names, aliases, UPNs, and email style strings such as Jamal Hartnett email@example.com.
Working with AAD users and groups
For VSTS customers backing their accounts with Azure Active Directory (AAD), management of AAD users and groups should be performed with the Azure AD Graph API Reference.
The VSTS Graph API can reference AAD user and groups but cannot be used ot modify them.