Roles to have permissions for /api/machines/discover

Hi team,

as per wiki:

GET /api/machines/discover HTTP/1.1
Interrogate a machine for communication details so that it may be added to the installation.


Users must be authenticated with an API key to perform this action.
Access is restricted to users in teams with MachineView permission covering relevant resources.

So, I have created a New role with permissions below:


I have created a service user and api key for it. Assigned this user to octopus team, and this team has my new role only assigned. Meaning, my service user and team x has only permissions above.

Now i’m trying to invoke api for discover of machine to add it to environments page, using this service user i have created api key and i’m getting error, unauthorized… Any clue what i’'m doing wrong or likely there is a bug or i’m missing another permissions for role? I’m using 3.7.7 version of octopus

Invoke-RestMethod “$OctopusURL/api/machines/discover?host=$machineName&port=$machinePort&type=TentaclePassive” -Method Get -Headers $header
Invoke-RestMethod : The remote server returned an error: (401) Unauthorized.
At line:1 char:1

  • Invoke-RestMethod "$OctopusURL/api/machines/discover?host=$machineNam …
  •   + CategoryInfo          : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], WebException
      + FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand


Thanks for reaching out! Could you please send me an export of that user’s permissions so I can take a look at them?


I have attached requested file and also few screen shots.

Permissions_export_2017_04_21__06_46_31_UTC.csv (1 KB)


Thanks for sending over all that info! I tested this in Octopus 3.12.3 and in that version all the permissions you need are MachineView. Its highly possible that we changed the permissions for that since your version to make them a lot more accesible. Unfortunately I can’t confirm this change right now, as most of the team is in Australia and today is holiday over there.

Can I suggest you to upgrade to the latest Octopus and give this a try in that version? If that’s not possible, I could spin up an Octopus instance of the same version as yours and let you know which were the permissions needed back then. But I strongly recommend you to go forward and upgrade if that’s possible for you.


I have also tried on 3.11.11 and 3.12.6 version and i get same error - unauthorized.

Few things to try:

  • Could you try creating a brand new API key (making sure you are logged in with the right user)?

  • Could you add -verbose to the invoke-webrequest call so it prints the exact URL its trying to hit, and then make sure its properly formatted?

If that doesn’t do it, please send me the code snippet you are using so I can give it a try on my end.

In case it helps, this is the code snippet I used for testing


$OctopusURL = "Http://devbox:82"

$header = @{ "X-Octopus-ApiKey" = $APIKey }

Invoke-WebRequest "$OctopusURL/api/machines/discover?host=localhost&port=10933&type=TentaclePassive" -Headers $header

Ok, i’had scoped that team with viewmachines role for systemtest env only, so that’s why it didn’t work on 3.12.6. So all good, with latest version it works.

Cheers Dalmiro for help and assistance!