Use personal access tokens
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
A Personal Access Token (PAT) can serve as an alternative password for authenticating into Azure DevOps. This article guides you through the process of creating, utilizing, modifying, and revoking PATs for Azure DevOps.
About PATs
A Personal Access Token (PAT) serves as your security credentials for Azure DevOps. This PAT not only identifies you but also determines your accessibility and scope of access. Hence, PATs are as important as passwords and should be handled with the same level of caution.
If you're utilizing Microsoft tools, then your Microsoft account (MSA) or Microsoft Entra ID is a recognized and supported method. However, if you're using third-party tools that don't support Microsoft or Microsoft Entra accounts, or if you're reluctant to share your primary credentials with these tools, PATs are a safer alternative.
Create and manage PATs in the following two ways:
- User interface (UI): Through user settings, as detailed in this article
- PAT Lifecycle Management API
To establish PATs for non-Microsoft tools, you can either use Git credential managers or generate them manually. We recommend you to review our authentication guidance to help you choose the appropriate authentication mechanism. PATs serve as a straightforward alternative for smaller projects that don't need an extensive solution. Unless a credential manager is in use, users must input their credentials each time.
Create a PAT
Sign in to your organization (
https://dev.azure.com/{Your_Organization}).From your home page, open user settings
and select Personal access tokens.
Select + New Token.
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.
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, limit your token's scope to Agent Pools (Read & manage). To read audit log events, and manage and 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 enabled a policy which 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.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.
Important
- Handle a PAT with the same caution as your password and keep it a secret.
- For organizations backed by Microsoft Entra ID, it's necessary to sign in with your new PAT within 90 days; failure to do so renders the PAT inactive. For more information, see User sign-in frequency for Conditional Access.
Notifications
During the lifespan of a PAT, users receive two notifications - the first one at the time of creation and the second one seven days prior to 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.
For more information, see Configure an SMTP server and customize email for alerts and feedback requests.
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://MyOrganization.visualstudio.com/on MyMachine" 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 an Azure App Service web app deployment is set up by you or an administrator.
- 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.
Warning
If you suspect that a PAT exists in error, consider revoking the PAT and changing your password. As a Microsoft Entra user, check with your administrator to see if your organization was used by an unknown source or location. Also, refer to the FAQ on accidental PAT check-ins to public GitHub repositories.
Use a PAT
Your PAT serves as your digital identity, representing you when utilized, much like a password does.
Git
Git interactions require a username, which can be anything except the empty string.
To use a PAT with HTTP basic authentication, use Base64-encode for $MyPat, which is included in the following code block.
In PowerShell, enter the following code.
$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
To keep your token more secure, use credential managers so you don't have to enter your credentials every time. We recommend Git Credential Manager. Git for Windows is required.
Existing repos
For existing repositories, if you already added the origin using the username, run the following command first.
git remote remove origin
Otherwise, run the following command.
git remote add origin https://<PAT>@<company_machineName>.visualstudio.com:/<path-to-git-repo> path to git repo = <project name>/_git/<repo_name> git push -u origin --all
Use a PAT in your code
You can use a PAT in your code.
To provide the PAT through an HTTP header, first convert it to a Base64 string. The following example shows how to convert to Base64 using C#.
Authorization: Basic BASE64_USERNAME_PAT_STRING
The resulting string can then be provided as an HTTP header in the following format.
The following sample uses the HttpClient class in C#.
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());
}
}
Tip
When you're using variables, add a $ at the beginning of the string, like in the following example.
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.
For more information and examples of how to use PATs, see the following articles:
- Git credential managers
- REST APIs
- NuGet on a Mac
- Reporting clients
- Get started with Azure DevOps CLI
Modify a PAT
You can regenerate, extend a PAT, or alter its scope. Once regenerated, the previous PAT becomes unauthorized.
From your home page, open your user settings, and then select Profile.
Under Security, select Personal access tokens. Select the token you want to modify, and then Edit.
Edit the token name, token expiration, or the scope of access associated with the token, and then select Save.
Revoke a PAT
You can revoke a PAT at any time, for many reasons.
From your home page, open your user settings, and then select Profile.
Under Security, select Personal access tokens. Select the token for which you want to revoke access, and then select Revoke.
Select Revoke in the confirmation dialog.
Related articles
- About security, authentication, and authorization
- Default permissions and access for Azure DevOps
- Revoke user PATs (for admins)
- Manage service principals and managed identities in Azure DevOps
FAQs
Q: Why can't I edit or regenerate a PAT that's scoped to a single organization?
A: Ensure you're signed into the organization where your PAT is scoped. You can view all of your PATs while signed into any organization in the same Microsoft Entra ID, but you can only edit organization-scoped tokens when you're signed into the organization to which they're scoped.
Q: What happens to a PAT if a user account is disabled?
A: Once a user's removed from Azure DevOps, the PAT is invalidated within 1 hour. If your organization is connected to Microsoft Entra ID, the PAT is also invalidated in Microsoft Entra ID, as it belongs to the user. We recommend that the user rotates their PAT to another user or service account to keep services running.
Q: Is there a way to renew a PAT via REST API?
A: Yes, there's a way to renew, manage, and create PATs using our PAT Lifecycle Management APIs. For more information, see Manage PATs using REST API and our FAQ.
Q: Can I use basic auth with all Azure DevOps REST APIs?
A: No. You can use basic auth with most Azure DevOps REST APIs, but organizations and profiles only support OAuth. For more information, see Manage PATs using REST API.
Q: What happens if I accidentally check my PAT into a public repository on GitHub?
A: Azure DevOps scans for PATs checked into public repositories on GitHub. When we find a leaked token, we immediately send a detailed email notification to the token owner and log an event to your Azure DevOps organization's audit log. Unless you disabled the Automatically revoke leaked personal access tokens policy, we immediately revoke the leaked PAT. We encourage affected users to mitigate immediately by revoking the leaked token and replacing it with a new token.
For more information, see Revoke leaked PATs automatically.
Q: Can I use a personal access token as an ApiKey to publish NuGet packages to an Azure Artifacts feed using the dotnet/nuget.exe command line?
A: No. Azure Artifacts doesn't support passing a personal access token as an ApiKey. When using a local development environment, we recommended installing the Azure Artifacts Credential Provider to authenticate with Azure Artifacts. For more information, see the following examples: dotnet, NuGet.exe. If you want to publish your packages using Azure Pipelines, use the NuGet Authenticate task to authenticate with your feed example.
Q: Why did my PAT stop working?
A: PAT authentication requires you to regularly sign into Azure DevOps using the full authentication flow. Once every 30 days is sufficient for many, but you may need to sign in more often than that depending upon your Microsoft Entra configuration. If your PAT stops working, first try signing into your organization, ensuring that you go through the full authentication prompt. If your PAT still doesn't work after that, check to see if your PAT has expired.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for