Authenticate with personal access tokens

Azure DevOps Services | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015

If you are working on a larger application or project we recommend you review our authentication guidance to help you choose the correct authentication mechanism. For smaller projects that require a less robust solution, personal access tokens are a simple alternative. Be aware that unless your users are using a credential manager (hyper link to below), they will have to enter their credentials each time.

These APIs support OAuth for authorization and you should plan to use that. With Oauth your users don't have to provide their Azure DevOps 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 access

  1. Sign in to your organization in Azure DevOps (https://dev.azure.com/{yourorganization})

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

    My profile Team Services

  3. Select + New Token.

    Select New Token to create

  4. Name your token, select the organization where you want to use the token, and then choose a lifespan for your token.

    Enter basic token information

  5. Select the scopes for this token to authorize for your specific tasks.

    For example, to create a token to enable a build and release agent to authenticate to Azure DevOps Services, limit your token's scope to Agent Pools (Read & manage), and then select Create.

    Select scopes for your PAT

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

    Copy the token to your clipboard

  1. Sign in to your Team Foundation Server web portal (https://{server}:8080/tfs/).

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

    TFS home page, open your profile, go to Security
  3. Create a personal access token.

    Add a personal access token
  4. Name your token. Select a lifespan for your token.

    If you're using Azure DevOps Services, and you have more than one organization, you can also select the organization where you want to use the token.

    Name your token, select a lifespan. If using Azure DevOps Services, select an account for your token
  5. Select the scopes for this token to authorize for your specific tasks.

    For example, to create a token to enable a build and release agent to authenticate to TFS, limit your token's scope to Agent Pools (read, manage).

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

    Use a token as the password for your Git tools or apps

Use your personal access token

Your token is your identity and represents you when it's used. Keep your tokens secret and treat them like your password.

See the following examples of using your PAT.

  • Username: anything
  • Password: your PAT here

or

  • git clone https://anything:@dev.azure.com/yourOrgName/yourProjectName/_git/yourRepoName

To keep your token more secure, use credential managers so you don't have to enter your credentials every time. We recommend the following credential managers:

Revoke personal access tokens to remove access

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

  1. From your home page, open your profile. Go to your security details.

    Azure DevOps Services

    Go to the organization home page, open your profile, go to Security

    Azure DevOps Server (formerly TFS)

    Go to the Azure DevOps Server home page, open your profile, go to Security
  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://dev.azure.com/{organization}/_apis/build-release/builds

If you wish to provide the personal access token through an HTTP header, you must first convert it to a Base64 string (the following example shows how to convert to Base64 using C#). The resulting string can then be provided as an HTTP header in the format:
Authorization: Basic BASE64USERNAME:PATSTRING
Here it is in C# using the HttpClient class.
public static async void GetBuilds()
{
    try
    {
        var personalaccesstoken = "PATFROMWEB";

        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}", "", personalaccesstoken))));

            using (HttpResponseMessage response = client.GetAsync(
                        "https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=5.0").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.

Enabling IIS Basic Authentication invalidates using PATs for TFS

Learn more about using IIS Basic Authentication with TFS on-premises.

Q & A

Q: Can I use basic auth with all of Azure DevOps REST APIs?

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