Rotating or replacing your PAT

You replace the personal access token (PAT) ADO Pilot uses by minting a new one in Azure DevOps and pasting it into the Integration settings page in your dashboard. There are two times you do this: on a 90-day schedule, and immediately after any suspected compromise.

When to rotate

Scheduled rotation (every 90 days)

Azure DevOps PATs expire on a fixed date. We recommend a 90-day expiration window — short enough to limit blast radius, long enough that rotation is a quarterly task instead of a weekly one. Plan to rotate before the existing token expires; if it lapses, reviews stop firing until you replace it.

Emergency rotation (rotate now)

Rotate immediately if any of these happen:

• The token string was pasted somewhere it shouldn't be — chat, email, a screenshot, an unencrypted note, a public log.
• A laptop or password vault that held the token was lost or compromised.
• The user who created the token has left your organization or had their access revoked.
• You discover the existing token has scopes broader than the three ADO Pilot needs (for example, Full access).
• Your security team flags any incident that touches the workstation where the token was created.

When you rotate for an emergency, mint the new PAT first, save it in ADO Pilot, then revoke the old one in Azure DevOps. That sequence avoids a coverage gap.

Required scopes for the new token

The replacement PAT needs the same scopes as the original. There are no additional scopes for rotation:

ADO Pilot needs the following Azure DevOps personal access token (PAT) scopes. Pick exactly these — do not grant Full access.

ADO Pilot's onboarding wizard probes the Code scope at validation time. The Code Status and Pull Request Threads scopes are exercised when the wizard provisions service hook subscriptions and when ADO Pilot posts the first review. A PAT missing any of them will fail later in onboarding or at first review with a scope error — re-create the token with all three scopes selected if you see one.

How to rotate

Rotating the PAT is an org-admin action. If you don't see a Rotate PAT button on the Integration settings page, ask an ADO Pilot admin for your organization to do it instead.

Step 1 — Create a new PAT in Azure DevOps

Follow Creating a Personal Access Token to mint a fresh token with all required scopes and a 90-day expiration. Copy the token string the moment Azure DevOps shows it — you only get one chance.

Step 2 — Open the Integration settings page

In the ADO Pilot dashboard, go to Settings then Integration. The Personal Access Token card shows the existing token's expiration date and remaining days.

Step 3 — Paste the new token

1. Click Rotate PAT.
2. In the dialog, paste the new token into the New PAT field.
3. Click Save token.

If you have not signed in recently, ADO Pilot may ask you to re-confirm your identity before saving — this step-up prompt is expected for credential changes.

The dialog notes that the old token is replaced atomically — ADO Pilot starts using the new token for its next outbound call. The old PAT is NOT revoked in Azure DevOps automatically; it remains valid in Azure DevOps until its original expiry date or until you manually revoke it (see Step 5). If you want to prevent the old token from being used elsewhere, you must revoke it yourself.

Step 4 — Confirm the connection is healthy

The Integration page should now show:

• The connection status indicator green.
• Service hook subscriptions re-provisioned and reconciled against Azure DevOps.

Push a small commit to a test branch and open a draft PR to confirm a review fires. If it does not, see PAT scope errors and Connection status shows "Unknown".

Step 5 — Revoke the old token in Azure DevOps

Go to User Settings → Personal access tokens in Azure DevOps, find the previous token by name, and click Revoke. Skipping this step is the most common rotation mistake — the old token remains valid until its original expiry date, which defeats the point of rotating after a compromise.

What stays the same after rotation

• Repository configuration (which repos are reviewed, exclusion patterns, severity thresholds).
• Review history, comments, and status checks already posted on existing PRs.
• Your plan, billing, team membership, and review credit balance.

What changes

• The stored PAT credential, encrypted at rest in our backend.
• Outbound calls from ADO Pilot to Azure DevOps now sign with the new token.
• Service hook subscriptions in Azure DevOps are re-provisioned and reconciled automatically. They authenticate to ADO Pilot through a separate, per-tenant credential that PAT rotation doesn't touch.

Troubleshooting rotation

• Save fails with a scope or token error. ADO Pilot validates the new token against your Azure DevOps org before saving it, so an invalid token or one missing Code (Read) access is rejected in the dialog rather than saved. A token missing Code (Status) or Pull Request Threads instead passes this check and saves successfully, then fails later when ADO Pilot tries to post a status check or comment — see "Reviews stop firing after rotation" below. Re-check the scopes against Required PAT scopes and try again.
• Connection status still shows "Unknown" after a successful save. ADO Pilot hasn't recorded a fresh health check yet — this isn't caused by the new token itself. See Connection status shows "Unknown".
• Reviews stop firing after rotation. If the new token is missing Code (Status) or Pull Request Threads scope, or the service hook update did not propagate cleanly, see Webhook 401s and reviews stopped firing.
• You forgot to copy the new token before closing the Azure DevOps dialog. The token cannot be recovered. Revoke the half-created token in Azure DevOps and start over.