Permissions for Octopus API

I have a space in Octopus. In this space, there is a project set up that uses the API to select work items to send in an email using Powershell. This project works fine. It uses a token under my account and I am the admin.

I have a second space with a project. The project uses the identical Powershell code except the token is for a service account. When the email is generated, I get an error:

ERROR retrieving package release notes info: The remote server returned an error: (401) Unauthorized.

Both projects use a single on-prem tentacle server.

Based on documentation I’ve read, using a service account is advised for API stuff. The service account I am using is set up with a domain account in Octopus and is the same account under which the tentacle runs.

Questions: What permissions does a service account need in order make API calls? Is there a specific role I can assign to the service account so that the token will work without generating a 401?


Hi @iancwright,

Sorry to see you’re having issues.

For clarification, could you provide a copy of your Process JSON for both of these Processes?
You can find the Download as JSON button here:

You may upload both Processes here or upload via this secure link.

Looking forward to hearing back from you.


Hi @garrett.dass,

Can you answer the two questions I posed?

I’m not certain why you need JSON docs.

I’m asking specifically what permissions are needed in order for an Octopus service account to use the API.


Hi @iancwright,

Thank you for getting back to me.

The Process JSONs were requested to provide additional context for this use case.

Can you confirm that the Octopus Service Account been assigned to a Team within Octopus that has permissions for the second Space?

Let me know at your earliest convenience.


I added the service account to the space managers role after creating a Service Accounts team.

This has cleared up the issue with the HTTP error code. Ideally, I don’t want to grant this level to the account, but since I couldn’t get a straight answer after asking twice, I just used trial and error. I will continue to whittle down the permissions to determine which role is needed for API calls.

Right now, the API request is failing to find the package because the default URI being used I guess points to the default space, not the one I am using for a separate group within my company. The documentation is lacking on the github site, so I will work on figuring out the API for this.

Anyhow, for anyone else having the same issue, this info may help. I will post the role that works with the least privileges for making an API request when I find out what it is.

Hi @iancwright,

Thank you for getting back to me. I’m glad to hear you were able to get it working.

For clarification, the API does not require permissions that are any different than those of a User using the Octopus UI. Users and Octopus Service Accounts that require access to additional Spaces must be added to Teams with permissions for those Spaces. Teams can be configured as System Teams or Space Teams. More info here:

Let us know if you have any additional questions.


This topic was automatically closed 31 days after the last reply. New replies are no longer allowed.