TFS 2015 API调用报401未授权：构建代理账号凭据无效访问被拒

遇到这种情况很常见——Build Agent能正常跑构建，但调用REST API就报401，核心原因通常是构建执行权限和API读取权限不互通，或者认证方式没匹配上。下面是一步步排查和解决的方案：

1. 先确认Build Agent账号的API权限 #

TFS的构建执行权限和REST API的读取权限是分开的。哪怕Agent能完成构建，它可能没有读取构建历史的API权限：

• 打开TFS Web界面，进入目标项目/项目集合
• 点击齿轮图标进入设置 > 安全性
• 找到Build Agent所在的用户组（比如Project Collection Build Service Accounts或项目级的Build Service Accounts）
• 检查是否开启了以下权限：
  • Build > 查看构建定义
  • Build > 查看构建
• 如果是跨项目调用API，还要去项目集合级的安全设置里添加对应权限，保存后再测试

2. 确保用对了认证方式 #

TFS 2015的REST API对域账号支持NTLM认证，而个人账号可能用的是基本认证，两者不通用：

• 如果你用PowerShell调用API，别用Base64编码的基本认证，换成NTLM方式：

  # 显式传入Agent的域凭据
  $agentCred = Get-Credential -Message "输入Build Agent的域账号密码"
  Invoke-RestMethod -Uri "http://tfs-server:8080/tfs/Collection/Project/_apis/build/builds?api-version=2.0" `
    -Method Get -Credential $agentCred
  

• 如果Agent是用域账号运行的，也可以试试-UseDefaultCredentials参数，让脚本自动取Agent服务的运行账号凭据

3. 检查Build Agent服务的运行账号 #

很多人会忽略这一点：如果Build Agent服务是用本地系统账号运行的，它只能访问本地资源，没法通过域认证调用TFS API：

• 在构建服务器上打开services.msc，找到TFS Build Agent对应的服务（名称一般是VSO Agent (你的Agent名)）
• 右键选属性 > 登录标签，确认登录账号是你用来构建的域账号，而不是本地系统/本地服务
• 要是不对，改成正确的域账号，输入密码后重启服务

4. 验证权限的范围是否匹配API调用 #

如果你的API是调用项目集合级的构建历史（比如http://tfs-server:8080/tfs/Collection/_apis/build/builds），那Agent账号需要集合级的权限，而不是只给单个项目加权限。去项目集合的安全设置里补全权限就行。

5. 清除缓存的旧凭据 #

有时候服务器会缓存旧的凭据，导致API调用时用了错误的身份：

• 打开控制面板的凭据管理器，找到Windows凭据里和TFS服务器相关的条目，全部删除
• 重新运行脚本，确保用的是最新的Agent凭据

6. 用最简脚本测试排除干扰 #

先写一个极简的测试脚本，排除其他代码的影响：

$tfsUri = "http://你的TFS服务器:8080/tfs/你的集合/你的项目/_apis/build/builds?api-version=2.0"
$agentCred = New-Object System.Management.Automation.PSCredential(
    "DOMAIN\Agent账号",
    (ConvertTo-SecureString "Agent密码" -AsPlainText -Force)
)
try {
    $response = Invoke-RestMethod -Uri $tfsUri -Method Get -Credential $agentCred
    Write-Host "调用成功！构建数量：$($response.count)"
} catch {
    Write-Host "错误详情：$_"
}

如果这个脚本能成功，说明之前的代码有其他问题；如果还是失败，就回到权限和认证方式的排查。

内容的提问来源于stack exchange，提问作者user9081259