A Guide to Service Accounts in Atlassian Cloud - Part 3: Service Accounts in Practice
Part 3: Atlassian Service Accounts in Practice
Now that we’ve set up our Service Account, we need to understand how to use it. As we identified in Part 1 of the series, Service Accounts sole purpose (for now) is to be used for API calls.
To help you get started, I’ve collected common pitfalls and errors, that I’ve encountered or been reported. Disclaimer: I am NOT a developer and by no means a specialist on APIs. So please correct me if I’m wrong and I’ll update this article for future readers.
Understanding & Using the Atlassian API
The correct API
There are two ways to access Atlassian REST APIs.
The most common and well documented one is the one, that includes your site url, followed by the specific request:
https://your-site.atlassian.net/{endpoint}
This way of calling the API cannot be used with scoped tokens. And as Service Account tokens cannot be created without scope, this API won’t work with them.
Luckily, there is another way via the api.atlassian.com base url, and most endpoints should work with that by now (not tested all).
https://api.atlassian.com/ex/confluence/{cloudId}/{endpoint}
https://api.atlassian.com/ex/jira/{cloudId}/{endpoint}
Rather than your site url, you need your Cloud ID to specify the target site.
💡
Find your Cloud ID by calling “https://<your-site>.atlassian.net/_edge/tenant_info", replacing “your-site” with your site url.
💡
Adding the Token
The API Token can be sent in the Header as Bearer Token. It doesn’t need to be hashed and you don’t need the Service Account Email (this is only required for Basic Authentication, which is shown in a lot of tutorials and listed in documentation).
Example curl Code for listing all Confluence spaces, the Service Account has access to:
curl --request GET \
-H "Authorization: Bearer $TOKEN" \
--url "https://api.atlassian.com/ex/confluence/{cloudId}/wiki/api/v2/spaces?limit=250"
💡
Make sure to safely store the token.
Do:
- Store tokens in secret managers or password managers.
- Inject them into runtime via environment variables or secret volumes.
Don’t:
- Commit them to Git.
- Put them in Dockerfiles or plain config files.
- Paste them into public channels.
💡
Common pitfalls
Wrong API version
Only the latest API versions support the needed base url format and scoped access. Unsupported endpoints will results in 404s or 403s.
Pagination
Some endpoints use pagination. You can identify them by looking at the request parameters.
Note: The Confluence and Jira APIs use DIFFERENT ways of pagination. While Confluence uses cursor-based pagination, Jira uses off-set pagination. The specifics are documented in each API overview section.
Confluence: https://developer.atlassian.com/cloud/confluence/rest/v2/intro/#using
Jira: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#pagination
Internal Redirects
Some endpoints internally redirect to a different URL. One example is the “Get Attachment” endpoint in Confluence. Per default, redirecting is usually disabled.
For curl, you need to set the “location” flag.
curl --request GET \
-H "Authorization: Bearer $TOKEN" \
--location \
For Python it is the “allow_redirects” flag.
response = requests.get('http://example.com/redirecting-url', allow_redirects=True)
Incorrect token scopes or permissions
If you keep getting 401 or 403 responses, check your token scope. For best results, start with a very specific token for that one endpoint and only set the granular scope that is required for that specific endpoint.
Remember that not only the token needs to match but also App level Permissions (license + content access).
Using (Python) libraries
Python libraries, and probably most others, use the wrong API base url. As only the api.atlassian.net base url will work, the libraries cannot be used with Service Accounts.
Trial and Error
That’s the part I don’t like. A lot of this is trial & error. If you cannot create endless Service Accounts and Tokens, it’s easiest to test everything with a personal scoped token first. If it works for that, then test with the same scope with a Service Account.
Also, test against a Sandbox or Test environment especially with Write-Requests. But that should be self-explanatory. Right?
Service Accounts for API Calls in Automation
Nothing special here. Rather than using your personal Account to send Web Requests, you can use your Service Account Credentials for calls against the Atlassian API.
Remember to add the Authorization Header. Hide the Header once your setup is done to make sure nobody can copy that token!
💡
You can use Smart Values in the request body as well as the url. Note that you need to url encode those values: https://support.atlassian.com/automation/kb/url-encode-jira-smart-values-using-20-instead-of-character/
💡
Missing Features
As per usual, Atlassian delivered Service Accounts at a state where they have not yet reached their full potential. So there still are a few things, that won't work.
❌ Service Accounts as Rule Actors
The “Automation for Jira” user is a blessing and a curse at the same time. Before, you needed a “Technical User” Account to be able to mingle with anything Jira without traces back to yourself. Now, you can save a license and just use Automation for Jira. It has access to everything and virtually no limits. And that’s the problem. It doesn’t respect permission limits, even if a regular user is setting up the automation. Atlassian also realized that and rumors have it, that the Automation for Jira user will be deprecated in the near future. With Confluence Automation, Atlassian simply didn’t provide a “Confluence for Automation” user to begin with.
Service Accounts to the rescue. You’d think. Unfortunately, Atlassian doesn’t yet allow Service Accounts to be added as Rule Actors.
I’ve tried doing it via the UI, Rule Export/Import and updating the Rule via API. Everything failed. I also had the Support confirm this. So the only thing left to do is vote the feature request: [AUTO-2008] Ability to add Service Accounts as actors for Jira & Confluence Automation - Create and track feature requests for Atlassian products.
I also have a meeting with the Automation team in a couple of days so stay tuned for an update or part 4 :)
❌ Service Account for Rovo Connection
If you connect a Rovo Agent in your Automation, it will always use your user as a Connection. Meaning: Regarless of who triggers the Automation, Rovo will run with your access and permissions and return results respectively. I already flagged this as a risk for data leackage numerous times and am hoping that Service Accounts could become the answer to my prayers.
❌ Org Admin approved Self Service
Creating Service Accounts doesn't scale really well at the moment. I see the potential for some self service options where users can request certain things and Org Admins only need to approve. At the very least it would be great to see the Token Scopes and maybe the option to copy the token configuration.
That's it for now.
Thanks for following along.
In case you missed it:
Part 2: Setting up a Service Account
I'm interested: What APIs have you used successfully with Service Accounts? Let me know in the comments and I'll add them to this article!
Was this helpful?
Thanks!
Rebekka Heilmann _viadee_
11 comments