Merge pull request #8012 from MicrosoftDocs/users/chcomley/438914-use-pats-update

PATs/Entra update use-personal-access-tokens-to-authenticate.md

Author: prmerger-automator[bot]

docs/organizations/accounts/use-personal-access-tokens-to-authenticate.md

@@ -9,7 +9,7 @@ ms.assetid: d980d58e-4240-47c7-977c-baaa7028a1d8
 ms.topic: how-to
 ms.author: chcomley
 author: chcomley
-ms.date: 05/22/2025
+ms.date: 06/09/2025
 monikerRange: '<= azure-devops'
 ---
 
@@ -19,7 +19,7 @@ monikerRange: '<= azure-devops'
 
 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. Treat PATs with the same level of caution as passwords.
 
-When you use Microsoft tools, your Microsoft account (MSA) or Microsoft Entra ID is recognized and supported. If you use tools that don't support Microsoft Entra accounts or don't want to share your primary credentials, PATs can be a suitable alternative. However, we recommend using [Microsoft Entra tokens](../../integrate/get-started/authentication/entra.md) over PATs whenever possible.
+When you use Microsoft tools, your Microsoft account (MSA) or Microsoft Entra ID is recognized and supported. If you use tools that don't support Microsoft Entra accounts, or if you prefer not to share your primary credentials, consider using PATs as an alternative authentication method. However, we recommend using [Microsoft Entra tokens](../../integrate/get-started/authentication/entra.md) over PATs whenever possible.
 
 [!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)]
 
@@ -55,8 +55,8 @@ When you use Microsoft tools, your Microsoft account (MSA) or Microsoft Entra ID
    :::image type="content" source="media/pats/select-pat-scopes-preview.png" alt-text="Screenshot showing selected scopes for a PAT.":::
 
    > [!NOTE]
-   > Your admin(s) may [restrict you from creating full-scoped PATs or limit you to packaging-scope PATs only](manage-pats-with-policies-for-administrators.md). Reach out to your admin to get on the allowlist if you need access to additional scopes.
-   > Some scopes, e.g. `vso.governance`, may not be available in the UI if they aren't for widespread public use.
+   > Your administrator might [restrict you from creating full-scoped PATs or limit you to packaging-scope PATs only](manage-pats-with-policies-for-administrators.md). Reach out to your admin to get on the allowlist if you need access to more scopes.
+   > Some scopes, for example, `vso.governance`, might not be available in the UI if they aren't for widespread public use.
 
 6. When you're done, copy the token and store it in a secure location. For your security, it doesn't display again.
 
@@ -66,17 +66,17 @@ Use your PAT anywhere your user credentials are required for authentication in A
 
 > [!IMPORTANT]
 > - Treat a PAT with the same caution as your password and keep it confidential. **DO NOT SHARE PATS.**
-> - For organizations backed by Microsoft Entra ID, you must sign in with your new PAT within 90 days or it will become inactive. For more information, see [User sign-in frequency for Conditional Access](/azure/active-directory/conditional-access/howto-conditional-access-session-lifetime).
+> - For organizations backed by Microsoft Entra ID, you must sign in with your new PAT within 90 days or it becomes inactive. For more information, see [User sign-in frequency for Conditional Access](/azure/active-directory/conditional-access/howto-conditional-access-session-lifetime).
 
 ### Notifications
 
 During the lifespan of a PAT, users receive two notifications: at time of creation and three days before expiration.
 
-After you create a PAT, you may receive a notification similar to below. This notification serves as confirmation that your PAT was successfully added to your organization.
+After you create a PAT, you might receive a notification similar to the following example. This notification serves as confirmation that your PAT was successfully added to your organization.
 
    :::image type="content" source="media/use-personal-access-tokens-to-authenticate/pat-creation.png" alt-text="Screenshot showing PAT created notification.":::
 
-An expiration notification email will be sent three days prior to expiration. If your admin has [removed your ability to create PATs in the organization](manage-pats-with-policies-for-administrators.md), the email will indicate that it is no longer possible for you to regenerate PATs. Reach out to your [Project Collection Administrator](../security/look-up-project-collection-administrators.md) to be included in an allowlist for continued PAT creation permissions in that organization.
+An expiration notification email is sent three days before expiration. If your administrator [removed your ability to create PATs in the organization](manage-pats-with-policies-for-administrators.md), the email indicates that it's no longer possible for you to regenerate PATs. Reach out to your [Project Collection Administrator](../security/look-up-project-collection-administrators.md) to be included in an allowlist for continued PAT creation permissions in that organization.
 
 ::: moniker range=" < azure-devops"
 
@@ -103,7 +103,7 @@ If you receive an unexpected PAT notification, it might mean that an administrat
 Your PAT serves as your digital identity, much like a password. You can use PATs as a quick way to do one-off requests or prototype an application locally. Use a PAT in your code to authenticate [REST APIs](/rest/api/azure/devops) requests and automate workflows by including the PAT in the authorization header of your request.
 
 > [!IMPORTANT]
-> Once your app code is working, switch to [Microsoft Entra OAuth to acquire tokens on-behalf-of your app's users](../../integrate/get-started/authentication/entra-oauth.md) or a [service principal or managed identity to acquire tokens as an application](../../integrate/get-started/authentication/service-principal-managed-identity.md). It is not recommended to keep running apps or scripts with PATs long-term. Microsoft Entra tokens can be used anywhere a PAT is used.
+> Once your app code is working, switch to [Microsoft Entra OAuth to acquire tokens on-behalf-of your app's users](../../integrate/get-started/authentication/entra-oauth.md) or a [service principal or managed identity to acquire tokens as an application](../../integrate/get-started/authentication/service-principal-managed-identity.md). It isn't recommended to keep running apps or scripts with PATs long-term. Microsoft Entra tokens can be used anywhere a PAT is used.
 > Consider [acquiring a Microsoft Entra token via the Azure CLI](../../cli/entra-tokens.md) for ad-hoc requests.
 
 #### [Windows](#tab/Windows/)
@@ -164,25 +164,25 @@ You can revoke a PAT at any time for these and other reasons:
 
 ## PAT Lifecycle Management APIs
 
-The [PAT Lifecycle Management APIs](/rest/api/azure/devops/tokens) may be useful when maintaining large volumes of tokens through UI is unsustainable. Managing PAT rotation programmatically also opens the opportunity to rotate PATs regularly and shorten their default lifespans. Our [sample Python app](https://github.com/microsoft/azure-devops-auth-samples/tree/master/PersonalAccessTokenAPIAppSample) can be configured with your Microsoft Entra tenant and Azure DevOps organization. 
+The [PAT Lifecycle Management APIs](/rest/api/azure/devops/tokens) might be useful when maintaining large volumes of tokens through UI is unsustainable. Managing PAT rotation programmatically also opens the opportunity to rotate PATs regularly and shorten their default lifespans. Our [sample Python app](https://github.com/microsoft/azure-devops-auth-samples/tree/master/PersonalAccessTokenAPIAppSample) can be configured with your Microsoft Entra tenant and Azure DevOps organization. 
 
 Some things to note about these APIs:
 
 * [Microsoft Entra access tokens](../../integrate/get-started/authentication/entra.md) are required to access this API as generally a stronger form of authentication is recommended when minting new tokens.
 * Only users or apps using an "on-behalf-of user" flow can generate PATs. Apps using "on-behalf-of application" flows or authentication flows that don't issue Microsoft Entra access tokens aren't valid for use with this API. As such, [service principals or managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md) can't create or manage PATs.
-* Previously the PAT Lifecycle Management APIs only supported the `user_impersonation` scope, but now the `vso.tokens` are available and the recommended scope to use with these APIS. Downscope all apps that previously relied on `user_impersonation` to call these APIs.
+* Previously the PAT Lifecycle Management APIs only supported the `user_impersonation` scope, but now the `vso.pats` are available and the recommended scope to use with these APIS. Downscope all apps that previously relied on `user_impersonation` to call these APIs.
 
 ## Changes to format
 
 As of July 2024, we updated the format of PAT strings to improve secret detection in our [leaked PAT detection tooling](manage-pats-with-policies-for-administrators.md#revoke-leaked-pats-automatically-tenant-policy) and [partner offerings](../../repos/security/github-advanced-security-secret-scanning.md). This new PAT format includes more identifiable bits to improve the false positive detection rate in these detection tools and mitigate detected leaks faster.
 
-* New tokens are now **84** characters long, with 52 characters being randomized data. This improves overall entropy, making tokens more resistant to brute force attacks.
+* New tokens are now **84** characters long, with 52 characters being randomized data, which improves overall entropy, making tokens more resistant to brute force attacks.
 * Tokens issued by our service include a fixed `AZDO` signature at positions 76-80.
 
-If you are using a PAT issued prior to that data, regenerate your PAT. If you integrate with PATs and have PAT validation built-in, update your validate code to accommodate both new and existing token lengths.
+If you're using a PAT issued before that data, regenerate your PAT. If you integrate with PATs and have PAT validation built in, update your validate code to accommodate both new and existing token lengths.
 
 > [!WARNING]
-> Both formats will remain valid for the foreseeable future. As adoption of the new format increases, we may retire older 52-character PATs.
+> Both formats remain valid for the foreseeable future. As adoption of the new format increases, we might retire older 52-character PATs.
 
 ## Best practices for using PATs
 
@@ -196,7 +196,7 @@ If you are using a PAT issued prior to that data, regenerate your PAT. If you in
 * Don't put personal data in the PAT name. Don't rename the PAT name to include some or all of the actual PAT token.
 * Avoid creating global PATs unless necessary across all organizations.
 * Use a different token per flow or user case.
-* Choose the minimally needed scopes per PAT. Create a separate PAT with fewer scopes for each flow, instead of a single full-scoped PAT for all flows. If your PAT needs read-only permissions, don't provide write permissions until necessary.
+* Select only the minimum scopes required for each PAT. Grant the least privilege necessary for your specific task, and create separate PATs with limited scopes for different workflows instead of using a single, broad-scoped token. If your PAT needs read-only permissions, don't provide write permissions until necessary.
 * Keep PAT lifespans short (weekly is ideal, even shorter is better).
 
 ### Managing PATs
@@ -209,13 +209,13 @@ If you are using a PAT issued prior to that data, regenerate your PAT. If you in
 ### For admins
 * Tenant admins can set [policies to restrict](manage-pats-with-policies-for-administrators.md) global PAT creation, full scoped PAT creation, and long-lived PAT duration.
 * Tenant admins can [revoke PATs for their organization users](admin-revoke-user-pats.md) if the PAT is compromised.
-* Organization admins can [restrict PAT creation in an organization](manage-pats-with-policies-for-administrators.md). If PATs are still needed, limit their creation to only those on the allowlist.
+* Organization admins can [restrict PAT creation in an organization](manage-pats-with-policies-for-administrators.md). If PATs are still needed, limit their creation to only ones on the allowlist.
 
 ## FAQs
 
 #### Q: Why can't I edit or regenerate a PAT scoped to a single organization?
 
-A: Sign into the organization where your PAT is scoped. You can view all your PATs while signed into any organization in the same Microsoft Entra ID by changing the *Access scope* filter, but you can only edit organization-scoped tokens when signed into the specific organization.
+A: Sign into the organization where your PAT is scoped. You can view your PATs when you're signed into any organization in the same Microsoft Entra ID by changing the *Access scope* filter, but you can only edit organization-scoped tokens when signed into the specific organization.
 
 #### Q: What happens to a PAT if a user account is disabled?
 
@@ -242,7 +242,7 @@ A: PAT authentication requires you to regularly sign into Azure DevOps using the
 Enabling IIS Basic Authentication invalidates using PATs for Azure DevOps Server. We recommend that you keep [IIS Basic Authentication](/iis/configuration/system.webserver/security/authentication/basicauthentication) turned **off** always. 
 
 > [!WARNING]
-> If you use Git with IIS Basic Authentication, Git breaks because it requires PATs for user authentication. You can adding an extra header to Git requests to use it with IIS Basic Authentication, but this is not recommended. The extra header must be used for all Azure DevOps Server installations, as Windows Auth also prevents using PATs. The extra header must also include a base 64 encoding of "user:PAT."
+> If you use Git with IIS Basic Authentication, Git breaks because it requires PATs for user authentication. You can add an extra header to Git requests to use it with IIS Basic Authentication, but we don't recommend this action. The extra header must be used for all Azure DevOps Server installations, as Windows Auth also prevents using PATs. The extra header must also include a base 64 encoding of `user:PAT`.
 >   ```
 >   git -c http.extraheader='Authorization: Basic [base 64 encoding of "user:password"]' ls-remote http://tfsserver:8080/tfs/DefaultCollection/_git/projectName
 >   ```
@@ -251,21 +251,21 @@ Enabling IIS Basic Authentication invalidates using PATs for Azure DevOps Server
 
 A: All PATs are associated with the user identity that created it. Applications can't create PATs.
 
-In Azure DevOps, you can create access tokens that aren't tied to a specific person by using Microsoft Entra tokens minted by an [application service principal or managed identity](../../integrate/get-started/authentication/service-principal-managed-identity.md). Within a pipeline, use [service connections](../../pipelines/library/service-endpoints.md).
+In Azure DevOps, you can generate access tokens that aren't linked to a specific user by using Microsoft Entra tokens issued by an [application service principal or managed identity](../../integrate/get-started/authentication/service-principal-managed-identity.md). For pipelines, use [service connections](../../pipelines/library/service-endpoints.md) to securely authenticate and authorize automated tasks without relying on user-specific credentials.
 
 ### Q: How can I regenerate/rotate PATs through the API? I saw that option in the UI, but I don’t see a similar method in the API.
 The 'Regenerate' functionality available in the UI actually accomplishes a few actions, which can be replicated through API. 
 
 To rotate your PAT, do the following steps:
 1. See PAT metadata with a **GET** call, 
-2. Create a new PAT with the old PAT id using a **POST** call, 
+2. Create a new PAT with the old PAT ID using a **POST** call, 
 3. Revoke the old PAT using a **DELETE** call.
 
-### Q: I see a "Need admin approval" pop-up when I try to use an Entra app to call the PAT Lifecycle Management APIs.
-Your tenant's security policies require admin consent before applications can access organization resources in the organization. Reach out to your tenant admin(s).
+### Q: I see a "Need admin approval" pop-up when I try to use a Microsoft Entra app to call the PAT Lifecycle Management APIs.
+Your tenant's security policies require admin consent before applications can access organization resources in the organization. Reach out to your tenant administrator.
 
 ### Q: Can I use a service principal to create or manage PATs?
-No, personal access tokens belong to a user identity. Entra [service principals or managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md) are able to generate short-lived Entra tokens that can be used in most places where a PAT is accepted. Learn more about [our efforts to reduce PAT usage across Azure DevOps](https://devblogs.microsoft.com/devops/reducing-pat-usage-across-azure-devops/) and explore replacing PATs with Entra tokens.
+No, personal access tokens belong to a user identity. Microsoft Entra [service principals or managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md) are able to generate short-lived Microsoft Entra tokens that can be used in most places where a PAT is accepted. Learn more about [our efforts to reduce PAT usage across Azure DevOps](https://devblogs.microsoft.com/devops/reducing-pat-usage-across-azure-devops/) and explore replacing PATs with Microsoft Entra tokens.
 
 
 ## Related articles