Personal Access Tokens and VSTS APIs

One of the great features of Visual Studio Team Services (VSTS) and Team Foundation Server (TFS) is its extensibility model. I am specifically referring to the REST APIs that Microsoft has started making available for their platform. Until recently, you had two options for authenticating with the REST APIs:

• Basic Authentication – requires that you enable alternate credentials on your VSTS/TFS account, Base64-encode them and send them “over the wire” along with your REST API call. This approach is simple though not very secure since your credentials are not encrypted “at rest” (though they are encrypted when used since the APIs utilize HTTPS at the transport layer). You can read more about using Basic Authentication with the REST APIs here.
• OAuth – this is a more secure approach than Basic Authentication, however it does require a bit more work to setup and utilize. If you are creating an application that requires access to the VSTS/TFS REST APIs (and, therefore must be authenticated) then OAuth is a great approach because you never need direct access to a user’s credentials. Rather, the APIs make use of an access token that is generated as part of the OAuth handshaking process. While the process isn’t tremendously complex it does require a bit of work up front and in your code to handle OAuth correctly. You can read more about using OAuth with the REST APIs here.

There is now a third option – Personal Access Tokens or, PATs. If you are not familiar with PATs then refer to Personal Access Tokens & VSTS. A PAT is something like a combination of the above two approaches in that it is as simple to use as Basic Authentication but does not provide direct access to your credentials like OAuth. It also has the ability to be scoped, just like OAuth.

To demonstrate this in action, I will be making use of a Fiddler to access the REST APIs. I will use Fiddler to compose an HTTP “GET” message to return a list of VSTS projects within my test collection. The HTTP call looks like this:

GET https://moonspace.visualstudio.com/DefaultCollection/_apis/projects?api-version=2.0

(If you’re following along at home, replace “moonspace” with your VSTS account name)

I must also provide the appropriate Authorization header which looks something like this:

Authorization: Basic QW55T2xkVXNlcjplaGc0Y3hxYjdodW9wcHJ4dGJra2ZtZ2x5Nm5yeWxrd3dwZjZsaGR4aXFkNzJ0NHJydDRx

Within the Composer tab in Fiddler, my call parameters look something like this:

The Base64-encoded string (just after “Authorization: Basic “ in the above screenshot) is the concatenation of my user ID and my personal access token (PAT). The format of the string to encode looks like this:

    UserName:PAT

Where “UserName” can be any user name you like (refer back to Personal Access Tokens & VSTS for more details) and PAT is the personal access token that you’ve created for use with your API calls. These two text values must be separated by a colon ( : ).

TIP: Pressing CTRL+E in Fiddler will display a Text Wizard where you can create the Base64-encoded string with ease. For example:

At this point you can click on the Execute button to send the HTTP GET command to VSTS. In my case, I received the following response:

You can see in the above screenshot that three projects were returned and I never had to provide my user credentials (that I use to sign in to VSTS with). Nor did I have to go through the typical OAuth setup process and/or sign-in process.

The nice things about PATs is that I can revoke them at any time (much like OAuth). Revoking a specific PAT will not have any impact on your user credentials or any other PATs that you might have created.

To demonstrate, I revoked the PAT created above and re-submitted the same API call with the following results:

Notice the “HTTP/1.1 401 Unauthorized” response. Cool!

So, if you are currently working with the VSTS/TFS REST APIs or you’re thinking about doing it sometime down the road, you now have yet one more option when it comes to authentication. As “they” say, options are a good thing… or, as a friend likes to say, “options are rare; therefore, they are valuable!” ;-)