Azure DevOps self-hosted agent cannot register to agent pool (GET works but POST returns 500/Forbidden)

Question

I am trying to register a self-hosted Azure DevOps agent on Ubuntu.

Environment

• Azure DevOps organization: https://dev.azure.com/<org>
• Agent version: 4.269.0
• OS: Ubuntu
• Authentication: PAT (Full access)

Steps

1. Download agent
2. Run ./config.sh
3. Enter organization URL
4. Enter PAT
5. Select agent pool

The agent configuration fails with the following error:

Forbidden

Failed to add the agent.

Diagnostic logs show:

Started GET request to https://dev.azure.com/<org>/_apis/distributedtask/pools/17/agents

Finished GET request with status code 200

Started POST request to https://dev.azure.com/<org>/_apis/distributedtask/pools/17/agents

POST request failed with HTTP Status: 500

Exception:

Microsoft.VisualStudio.Services.Common.VssServiceException: Forbidden

Observations

• GET request works (200)
• POST request fails (500 + Forbidden)
• PAT has Full Access
• Agent pool exists
• No existing agent in the pool

Question

Why would Azure DevOps allow GET but reject POST when registering a new agent?

Could this be related to agent pool permissions or organization policies?

Answer 1

Hello wewebplus,

The agent is able to successfully authenticate and connect to the Azure DevOps organization, as indicated by the successful GET request (HTTP 200) to the agent pool endpoint. However, the registration step fails during the POST request used to add the agent to the pool, which returns Forbidden.

This behavior typically occurs when the identity associated with the Personal Access Token (PAT) has permission to view or use the agent pool, but does not have sufficient permissions to register or manage agents in that pool.

Although the PAT is configured with Full Access, PAT scopes do not override Azure DevOps role-based access control (RBAC). The user who created the PAT must also have the appropriate Agent Pool permissions within the organization.

We recommend verifying the permissions for the PAT user by following these steps:

1. Navigate to Azure DevOps → Organization Settings.

Select Agent Pools.

Open the agent pool being used (Pool ID 17 in your logs).

Go to Security.

Ensure the user who generated the PAT has either:

Administrator permissions on the agent pool, or

  At minimum, permissions that include **Manage** and **Use**.
```Once the required permissions are granted, please try running the agent configuration again.

Additionally, please confirm the following:

The configuration is using the **organization URL** (e.g., `https://dev.azure.com/<org>`) and not a project-specific URL.

The PAT belongs to a user who is a **member of the Azure DevOps organization**.

After updating the permissions, re-running the `./config.sh` command should allow the agent to register successfully.  
  
Please accept as answer and do a Thumbs-up to upvote this response if you are satisfied with the community help. Your upvote will be beneficial for the community users facing similar issues.

 

Answer 2

The behavior is consistent with insufficient permissions for the identity that is registering the agent, not with the agent software itself.

Key points from the platform behavior in the context:

• Listing agents in a pool (GET) only requires read access to the agent pool.
• Creating/registering an agent in a pool (POST) requires administrator permissions on that agent pool, and the identity must be recognized as an organization user.
• The PAT scope alone is not enough if the underlying identity does not have the correct pool role.

From the documentation:

• “Someone with permission to administer the agent queue must complete these steps. The agent will not use this person's credentials in everyday operation, but they're required to complete registration.”
• “Make sure the user account that you're going to use has permission to register the agent. Is the user an Azure DevOps organization owner or TFS or Azure DevOps Server administrator? Stop here, you have permission. Otherwise: Open a browser and navigate to the Agent pools tab…”
• For adding identities (users or service principals) via Project settings → Agent pools, the identity must first be added as an organization user with Basic access level or higher.

Because GET works but POST returns Forbidden during registration, the most likely causes are:

1. The user associated with the PAT does not have Agent Pool Administrator (or higher) permissions on that pool.
2. The identity is not correctly added as an organization user with at least Basic access level.

To fix the issue:

1. Sign in to https://dev.azure.com/{yourorganization} with an account that is an organization owner or has permissions to manage agent pools.
2. Go to Organization settings → Agent pools.
3. Select the target pool and open Security.
4. Ensure that the user whose PAT is being used is present and has the Administrator role on that pool.
   • If the user is missing, add it.
   • If the user is present but only as User, change the role to Administrator.
5. If configuring via Project settings → Agent pools, verify that this user is added as an organization user with Basic access level or higher before assigning pool permissions.
6. Generate a PAT for that user with at least Agent Pools (read, manage) scope and re-run ./config.sh using that PAT.

Once the identity has the correct pool administrator permissions, the POST to /pools/{id}/agents should succeed and the agent will register correctly.

---

References:

• Self-hosted Linux agents
• Self-hosted Windows agents
• Create and manage agent pools
• Register an agent using a personal access token (PAT)
• Register an agent using device code flow
• Register an agent using a service principal