Get a List of VSTS Users with APIs

So, I’ve recently been preparing to switch our organization’s VSTS accounts over to be backed by Azure Active Directory and I have a need to export a list of all VSTS users within our accounts. After getting some assistance from the Visual Studio product group (thanks!) I was able to make use of the Member Entitlement Management API for VSTS. Since it’s been a while since I’ve done a VSTS API post I thought I’d share how to get a list of VSTS users (and other related information) using this API.

Postman

Previously, I’ve used Fiddler to quickly test API calls. In this post, I will use Postman to do the same. While Fiddler has some great features I like the simplicity of Postman’s user interface. If you’ve not used Postman, I would recommend downloading it and giving it a try!

Authentication

We will be using Personal Access Tokens (PATs) to authenticate when calling the API. If you are not familiar with PATs or how to properly format the Base64-encoded Authentication header then check out Personal Access Tokens and VSTS APIs. The short version is you need to obtain a PAT for the VSTS user you plan to authenticate with and create a Base64-encoded string with the contents in the format of:

  UserName:PAT

Next, add an Authorization header to Postman:

Calling the API

We need to add the URL for the API that we will be calling. The URL for this particular API is in the format of:

  https://{Account}.vsaex.visualstudio.com/_apis/userentitlements?api-version=4.1-preview

Simply replace {Account} with your specific VSTS account name. For my example, I am using moonspace:

  https://moonspace.vsaex.visualstudio.com/_apis/userentitlements?api-version=4.1-preview

Enter your specific API URL in Postman and select GET for the operation:

At this point, click the Send button. You should get a JSON result back listing information on each user configured within your VSTS account. The results of my call contained information on two users:

While this call only yielded two results, you might have VSTS accounts with hundreds of users. By default, this API will only return the first 100 users. If you want to retrieve more than 100 users you need to add the top query string parameter. For example, the following API call will return up to 1,000 users:

  https://{Account}.vsaex.visualstudio.com/_apis/userentitlements?api-version=4.1-preview&top=1000

Calling the API with C#

While you can use Postman (or Fiddler) to quickly test out various API calls it’s likely you’ll want to call the APIs from within your code. Postman can help get you started with this as well.

In Postman, look for the Code link just under the Save button and click it.

From the resulting dialog, select C# (RestSharp) (note the other language options available as well).

Postman will generate some quick-n-dirty C# code that you can then copy and paste into Visual Studio:

For this example, you’ll need to also install the RestSharp NuGet package.

Create the Models

With the above code, and the RestSharp NuGet package, you can immediately call the API with C# and get back a response. However, you’ll likely want to take it at least one step further and create a set of model classes to deserialize the API results into. This is pretty easy with Postman and Visual Studio.

1. In Postman, select the JSON results and copy them to the clipboard.
2. Place the cursor somewhere within the namespace brackets (I.e. not within another class definition) and click on Edit->Paste Special->Paste JSON as Classes.

Voila! You now have a set of classes that can be used to easily traverse the API results.

Deserialize!

Now that we have a set of model classes, let’s finish out our example with the following code:

static void Main(string[] args)
{
    // Asking for a maximum of 1000 users to be returned
    var client = new RestClient("https://YOUR-ACCOUNT-HERE.vsaex.visualstudio.com/_apis/userentitlements?api-version=4.1-preview&top=1000");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "Basic YOUR-PAT-HERE!");
    IRestResponse response = client.Execute(request);

    var users = JsonConvert.DeserializeObject<Rootobject>(response.Content);

    foreach (var user in users.value.OrderBy(x => x.user.mailAddress))// Sorting results by e-mail address
    {
        Console.WriteLine($"{user.user.mailAddress},{user.lastAccessedDate.ToLocalTime():yyyy-MM-dd HH:mm:ss},{user.accessLevel.licenseDisplayName}");
    }

    Console.ReadKey(); // Pause the command window (for testing)
}

In the case of the above example, I pasted the “JSON as Classes” just below the above code. I am not showing that code for brevity since it is auto-generated by Visual Studio.

Run!

At this point you can run the code and get a listing of your VSTS users along with the last date/time they accessed VSTS as well as the license type they have assigned to them. For example:

While these APIs are not fully fleshed out just yet (e.g. a continuation token is not yet supported) there can be very helpful when you need to programmatically obtain information about the users in your VSTS account(s).

Please let me know if you find this useful and/or have any questions. Enjoy!