Use personal access tokens

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

A Personal Access Token (PAT) serves as an alternative password for authenticating into Azure DevOps. This PAT identifies you and determines your accessibility and scope of access. Therefore, treat PATs with the same level of caution as passwords.

When you use Microsoft tools, your Microsoft account (MSA) or Microsoft Entra ID is a recognized and supported method. If you use non-Microsoft tools that don't support Microsoft or Microsoft Entra accounts, or if you prefer not to share your primary credentials with these tools, PATs are a suitable alternative.

This article guides you through creating, using, modifying, and revoking PATs for Azure DevOps.

You can manage PATs using the following methods:

• User interface (UI): Through user settings, as detailed in this article
• PAT Lifecycle Management API

To establish PATs for non-Microsoft tools, you can use Git credential managers or generate them manually. We recommend reviewing our authentication guidance to choose the appropriate authentication mechanism. PATs provide a straightforward alternative for smaller projects that don't require an extensive solution. Without a credential manager, users input their credentials each time.

Prerequisites

• Permissions:
  • Have permission to access and modify your user settings where PATs are managed.
    • Check permissions: To check your permissions, do either of the following processes in Azure DevOps:
      • Go to your profile and select User settings > Personal access tokens. If you can see and manage your PATs here, you have the necessary permissions.
      • Go to your project and select Project settings > Permissions. Find your user account in the list and check the permissions assigned to you. Look for permissions related to managing tokens or user settings.
  • If your organization has policies in place, an Azure DevOps Administrator might need to grant you specific permissions or add you to an allowlist to create and manage PATs.
  • Depending on the tasks you want to perform with the PAT, you might need additional permissions. For example:
    • Build: Read & execute
    • Code: Read, write, & manage
    • Environment: Read & manage
    • Project and team: Read, write, & manage
    • Variable groups: Read & create
• Access levels: Have at least Basic access.
• Security best practices: Familiarize yourself with security best practices for managing PATs, such as using them only when necessary and regularly rotating them.

Create a PAT

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

2. From your home page, open user settings and select Personal access tokens.

   

3. Select + New Token.

   

4. Name your token, select the organization where you want to use the token, and then set your token to automatically expire after a set number of days.

   

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

   For example, to create a token for a build and release agent to authenticate to Azure DevOps, set the token's scope to Agent Pools (Read & manage). To read audit log events and manage or delete streams, select Read Audit Log, and then select Create.

   

   Note

   You might be restricted from creating full-scoped PATs. If so, your Azure DevOps Administrator in Microsoft Entra ID has enabled a policy that limits you to a specific custom-defined set of scopes. For more information, see Manage PATs with policies/Restrict creation of full-scoped PATs. For a custom-defined PAT, the required scope for accessing the Component Governance API, vso.governance, isn't selectable in the UI.

6. When you're done, copy the token and store it in a secure location. For your security, it doesn't display again.

   

Use your PAT anywhere your user credentials are required for authentication in Azure DevOps.

Notifications

During the lifespan of a PAT, users receive two notifications: the first at the time of creation and the second seven days before its expiration.

After you create a PAT, you receive a notification similar to the following example. This notification serves as confirmation that your PAT was successfully added to your organization.

The following image shows an example of the seven-day notification before your PAT expires.

Unexpected notification

If you get an unexpected PAT notification, it might mean that an administrator or tool created a PAT for you. Here are some examples.

• A token named "git: https://dev.azure.com/{Your_Organization} on YourMachine" gets created when you connect to an Azure DevOps Git repo via git.exe.
• A token named "Service Hooks: : Azure App Service: : Deploy web app" gets created when you or an administrator sets up an Azure App Service web app deployment.
• A token named "WebAppLoadTestCDIntToken" gets created when web load testing is set up as part of a pipeline by you or an administrator.
• A token named "Microsoft Teams Integration" gets created when a Microsoft Teams Integration Messaging Extension is set up.

Use a PAT

Your PAT serves as your digital identity, much like a password.

Git

Git interactions require a username, which can be anything except an empty string. To use a PAT with HTTP basic authentication, Base64-encode your $MyPat as shown in the following code block.

$MyPat = 'yourPat'
$headerValue = "Authorization: Basic " + [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes(":" + $MyPat))
$env:GIT_AUTH_HEADER = $headerValue

git --config-env=http.extraheader=GIT_AUTH_HEADER clone https://dev.azure.com/yourOrgName/yourProjectName/_git/yourRepoName

MY_PAT=yourPAT # replace "yourPAT" with "PatStringFromWebUI"
export HEADER_VALUE=$(echo -n "Authorization: Basic "$(printf ":%s" "$MY_PAT" | base64))

git --config-env=http.extraheader=HEADER_VALUE clone https://dev.azure.com/yourOrgName/yourProjectName/_git/yourRepoName

Existing repositories

• Remove existing origin: If you previously added the origin using a username, remove it by running the following command:

  git remote remove origin

• Authenticate with a PAT: If you encounter issues with standard authentication, run the following command to authenticate via the command line:

  git remote add origin https://dev.azure.com/<PAT>@<company_machineName>:/<project-name>/_git/<repo_name>

  git push -u origin --all

  The path to git repo = /_git/do refers to the URL path structure used in Azure DevOps for Git repositories. The /_git/ segment indicates that you're accessing a Git repository, and you should replace do with the actual name of your repository. For example, if your repository is named my-repo, the path would be '/_git/my-repo'.

• Clone repository: If you're using Git and need to authenticate, run the following command:

  git clone https://{organization}@dev.azure.com/{organization}/_git/{repository}

  Replace {organization} with your Azure DevOps organization name and {repository} with the name of your repository.

Use a PAT in your code

You can use a PAT in your code to authenticate API requests and automate workflows. To do so, include the PAT in the authorization header of your HTTP requests.

Authorization: Basic BASE64_USERNAME_PAT_STRING

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());
    }
}

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());
   }
}

curl -u :{PAT} https://dev.azure.com/{organization}/_apis/build-release/builds

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

For more information and examples of how to use PATs, see the following articles:

• Set up Git credential managers
• Access REST APIs
• Use NuGet on a Mac
• Authenticate reporting clients
• Get started with Azure DevOps CLI

Changes to format

As of July 2024, we significantly changed the format of PATs issued by Azure DevOps. These changes provide more security benefits and improve secret detection tooling available through our partner offerings, like GitHub Advanced Security for Azure DevOps. This new PAT format follows the recommended format across all Microsoft products. The inclusion of more identifiable bits improves the false positive detection rate of these secret detection tools and enables us to mitigate detected leaks faster.

Key changes:

• Increased token length: The new tokens are now 84 characters long, with 52 characters being randomized data. This increased length improves overall entropy, making the tokens more resistant to potential brute force attacks.
• Fixed signature: Tokens issued by our service include a fixed AZDO signature at positions 76-80.

Action required:

• Regenerate existing PATs: We strongly recommend regenerating all PATs currently in use to take advantage of these security enhancements.
• Integrator support: Integrators should update their systems to accommodate both the new and existing token lengths.

Related articles

• Learn about security, authentication, and authorization
• Review default permissions and access for Azure DevOps
• Revoke user PATs (for admins)
• Manage service principals and managed identities in Azure DevOps