When you need this guide
Git-Zen prefers OAuth 2.0 for Azure DevOps connections — it's automatic, refreshes on its own, and ties to your account. Use a Personal Access Token (PAT) instead when:
- OAuth login fails because of a corporate Entra ID (Azure AD) policy that blocks third-party app consent.
- You want Git-Zen to run under a service account rather than a personal account.
- You're switching back to PAT after an OAuth user lost their permissions to the org.
Required scopes
Git-Zen needs the following scopes on your PAT. Anything more is unnecessary; anything less and parts of the integration will fail silently.
| Scope | Permission | Why Git-Zen needs it |
|---|---|---|
| Work Items | Read & write | Create work items from Zendesk tickets, sync field updates and comments. |
| Code | Read | Read commits referenced from Zendesk tickets via gz# tags. |
| Identity | Read | Resolve assignee names when creating work items. |
| Project and Team | Read | List your projects, teams, area paths, and iteration paths in the Git-Zen sidebar. |
| Service Connections | Read & query | Configure and query service hooks (webhooks) for inbound updates. |
Step-by-step
Open Personal Access Tokens in Azure DevOps
Go to dev.azure.com/{your-org} and click your profile picture in the top-right.
Select Personal access tokens from the dropdown menu.
Create a new token
Click + New Token. Fill in:
- Name:
Git-Zen Integration - Organization: the org Git-Zen will sync (you can repeat this process for additional orgs)
- Expiration: 1 year (the longest Azure DevOps allows by default; some orgs limit to 90 days). Set a calendar reminder to rotate before it expires.
Select scopes
Click Show all scopes, then choose Custom defined and check the boxes from the table above.
Copy the token immediately
Click Create. Azure DevOps shows the token once. Copy it to your clipboard or a password manager right now — if you close the dialog without copying, you have to start over.
Paste the token into Git-Zen
Inside Zendesk, open any ticket and find the Git-Zen sidebar. Then:
- Click the gear icon → Settings
- Open the Authentication section
- Switch from OAuth to PAT
- Paste the token and click Save
Git-Zen will validate the token immediately. If something is wrong with the scopes, the validator tells you which scope is missing.
Multiple Azure DevOps organizations
Need Git-Zen to talk to more than one Azure DevOps organization? Each org gets its own PAT (they're scoped per-org). Today this requires a quick email to support to provision the additional org — we're tracking self-serve multi-org as a feature in our roadmap. Email us with your org name(s) and we'll have it set up the same day.
Troubleshooting
"Unauthorized" or 401 errors after pasting
- Confirm you copied the token without surrounding whitespace.
- Confirm the token's organization matches the org you've configured in Git-Zen.
- If your org enforces conditional access policies, ensure PATs are allowed for your account.
"Forbidden" or 403 errors
- Most likely a missing scope — recreate the PAT and re-check the scope list above.
- If you're using a service account, verify it has at least Stakeholder access to the project (Basic + access to Boards is recommended).
The token expired
Azure DevOps emails you 7 days before expiration. Repeat steps 1–5 to create a new one and paste it into Git-Zen Settings. Git-Zen will keep your settings, links, and history intact during the rotation.
Security best practices
- Use the shortest expiration your security policy allows.
- Use a service account rather than a personal account when possible — tokens don't break when employees leave.
- Use the minimum scopes from the table above — never "Full access".
- Store the token in a password manager or secret vault, not in plain text.
- Rotate annually even if not required — pair it with your other annual security tasks.
Other auth setup guides
GitHub Personal Access Tokens → · GitLab Personal Access Tokens → · Back to Git-Zen for Azure DevOps →