Table of contents
TOC
Collapse the table of content
Expand the table of content

Basic authentication for the REST APIs

Last Updated: 7/8/2016

These APIs support OAuth for authorization and you should plan to use that. With Oauth your users don't have to provide their Visual Studio Team Services credentials to use when the APIs are called. To get started on your app, though, you can authenticate using personal access tokens.

Create personal access tokens to authenticate account access

  1. Sign in to your Visual Studio Team Services account (https://{youraccount}.visualstudio.com).

  2. From your account home page, open your profile. Go to your account's security details.

    Account home page, open your profile, go to My security

  3. Create a personal access token for your Team Services account.

    Add a personal access token

  4. Name your token. Select a lifespan and the Visual Studio Team Services account where you want to use the token.

    Select a lifespan and Team Services account

  5. Select the scopes that this token authorizes.

    Select scopes for this token

  6. When you're done, make sure to copy the token. You'll use this token as your password.

    Use token as the password for your git tools or apps

    Note: Remember that this token is your identity and acts as you when it's used. Keep your tokens secret and treat them like your password.

    Tip: To keep your token more secure, use credential managers so that you don't have to enter your credentials every time. Here are some recommended credential managers:

    For example, if you use the Git command prompt to run a Git command, you'll be prompted for a username and password.

    git clone https://{account}.visualstudio.com/DefaultCollection/_git/{team project}
    

    Enter a username that does not contain an @ character (for example, Jamal, not fabrikamfiber4@hotmail.com). Use the token that you created as your password.

    Username for 'https://fabrikam-inc.visualstudio.com': Jamal
    Password for 'https://fabrikam-inc.visualstudio.com': [COPY THE TOKEN HERE]
    

Revoke personal access tokens to remove access

When you don't need your token anymore, just revoke it to remove access.

  1. Go to your team project's home page and open your profile.

    Team project home page, my profile

  2. Revoke access.

    Revoke a token or all tokens

Here's a sample that gets a list of builds using curl.

curl -u username[:{personalaccesstoken}] https://{account}.visualstudio.com/DefaultCollection/_apis/build/builds

Here it is in C# using the HttpClient class.

public static async void GetBuilds()
{
    try
    {
        var username = "username";
        var password = "password";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Accept.Add(
                new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
                Convert.ToBase64String(
                    System.Text.ASCIIEncoding.ASCII.GetBytes(
                        string.Format("{0}:{1}", username, password))));

            using (HttpResponseMessage response = client.GetAsync(
                        "https://{account}.visualstudio.com/DefaultCollection/_apis/build/builds").Result)
            {
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.ToString());
    }
}

When your code is working, it's a good time to switch from basic auth to OAuth.

Q&A

Q: Can I use basic auth with all of the Visual Studio Team Services REST APIs?

A: No. You can use basic auth with most of them, but accounts and profiles only support OAuth.

© 2016 Microsoft