nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

A Guide to Service Accounts in Atlassian Cloud - Part 2: Setting up a service account

Rebekka Heilmann (viadee)

After understanding Service Accounts , we need to set them up. Thanks again to @Darryl Lee for the review and contribution!

Before we go crazy with the account creation though, there are a few things that we should consider.

For one, Account creation and setup needs Organization Administration privileges. As a regular user, you will need help. However, you can come prepared if you are aware of all the info your Org Admin will need for you. Jump straight ahead to the step-by-step guide and come back for part 3. That one’s for you.

Secondly, Atlassian is not making it very easy to keep track of all Accounts, Tokens, Owners etc. That’s why we need some…

…Best Practices for Administration & Governance

Service accounts often end up with a lot of power and very long lives. There is a team or person that requested the account and therefore a use case. If we create accounts with documentation of that, we will not remember in a few years when an audit is coming up and we need to account for everything happening on our sites.

Documentation of Service Account

For every service account, track at least:

Owner (named person or team)
Purpose / systems using it
Tokens & Expiration date (you can check the Scope in the UI later on)

Tokens and their expiration dates as well as scopes actually do not need to be documented separately anymore as there is a new API available for this. Check out Part 4 for more details.

You can use the description field in the Service Account. This information is returned by the API Access API so you can run automatic checks and find the owner for each Account, as long as you follow the same format each time.

You could also set up something a little more sophisticated if that suits your governance needs better. For example, if you are tracking Confluence & Jira spaces per Team already in Assets, it makes sense to add Service Accounts there also.

Rotation and expiry

Plan for token expiration - any token is valid for 365 days max; Set expiration dates on a set date every month so tokens don't run out at random points in time
Set calendar reminders, automation, or monitoring for upcoming expiry
When rotating:
1. Create a new token and share with Account owner
2. (Remind owners to) update all scripts/integrations
3. Revoke the old token

Check out Part 4 of this series for more details on token renewal

Create with least privilege

Minimal App access
Minimal scopes
Minimal permissions

Only widen when there is a justified need. Beware that Service Accounts will be added to Default App Access groups just like any regular user. You might want to manage App Access via separate groups that have limited Global Permissions or Space permissions.

Consider Self Service Options

If your company is in need of a lot of Service Accounts, you as an Org Admin may get very busy with Account and Token creation. Depending on the expiration date, new Tokens need to be created at least every year.

Consider things like

A request form for new Accounts
A request form for App access change
A request form for new Tokens
A system triggered request that prompts the Account owner to approve token renewal (if there is no response, tokens run out and the Account may be ready for deletion)

Right. Let’s jump into the actual guide.

Setting up a service account - a step-by-step guide

Step 1: Design the use case first

Before creating or requesting anything, write down:

What will this integration do?
- “Read issues from Project A and update a few custom fields.”
- “Create Confluence pages in Space X with release notes.”
Which products and areas are involved?
- Jira? Confluence? Which projects/spaces?
What’s the minimum it needs to do?
- Read only vs read + write vs delete?
- Does it really need admin‑level powers?

Then map that into scopes using the REST API docs:

Jira Cloud REST API: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/
Jira Service Management REST API: https://developer.atlassian.com/cloud/jira/service-desk/rest/intro/
Confluence Cloud REST API: https://developer.atlassian.com/cloud/confluence/rest/intro/

💡
Make sure that a Service Account is actually what you need. Some Use Cases may be better covered by Personal API Access Tokens, Filter Subscriptions, Out-of-the-Box Features, Marketplace Apps… Check out Part 1 of this series.
💡

Step 2: Create the service account (Org Admin only)

Go to admin.atlassian.com and select your organization.
Open Directory → Service accounts.
Create a new service account:
- Give it a clear, purpose‑driven name, like:
  - jira-ci-cd-bot
  - confluence-reporting-bot
- Optionally add a description including a human owner/contact.
Give it App access (Jira, Confluence, Goals, … ) in the correct role (User, Customer, App Admin…)
Optionally add it to groups

Details to this flow can change over time, so always check Atlassian’s docs: https://support.atlassian.com/user-management/docs/understand-service-accounts/

💡
You may want to manage App Access for Service Accounts via special groups so they are not added to any Default Access groups automatically. Default Groups may be used for Global or Space Level Permissions.

If so:

Create Groups that grant access to specific App roles
e.g. “service-account-jira-user” > Grants access to Jira in the Role “User”
Add the Groups to App Access (see https://support.atlassian.com/user-management/docs/give-users-access-to-products/ )
Make sure these Groups have the correct Global App Permissions in each App
Add Service Accounts to the respective groups

💡

Step 3: Create a credential for the service account (Org Admin only)

See https://support.atlassian.com/user-management/docs/manage-api-tokens-for-service-accounts/ for reference.

Once the service account exists:

Go to admin.atlassian.com and select your organization.
Go to Directory → Service accounts.
Choose the service account → Actions → Create credentials.
Configure:
- Authentication type: API token or OAuth2
- App & Scope: pick only what this integration needs (read / write / delete)
- Expiration: 1–365 days, aligned with your rotation policy
Review and document the scope before creating it.
Copy it and store/share it securely (password manager, secret manager, etc.)

💡
Atlassian recommends to use classic scopes. Some granular scopes are not part of any classic scope so they need to be granted specifically, if the endpoint requires them.

Best practise for scope: start with least privilege and create other access tokens when your integration proves it needs more.

Atlassian doesn’t store the raw token; if you lose it, you need to create a new one.

Also: You cannot view or edit the token scope after creation. Documentation is key for later troubleshooting.
💡

Step 4: Give it permissions in Jira and Confluence (Space Admin)

Now that the Service Account is created, you need to give it access on App level. Add it to your Confluence or Jira Space, your Compass team or wherever else it needs access to. This step can be completed by the respective Space Admins.

You can find and add Service Account like any other regular User and simply search for their name.

https://support.atlassian.com/confluence-cloud/docs/assign-space-permissions/
https://support.atlassian.com/jira-software-cloud/docs/add-users-to-space-roles-in-your-space/

Bonus Step: Update the Avatar

The wonderful @Darryl Lee commented this on part 1, but I thought it's worth mentioning it here. You can update the Service Account's avatar via an undocumented API.

Well, it's sort of documented in this JAC: https://jira.atlassian.com/browse/AX-278

Example:

<span data-testid="renderer-code-block-line-1" data-ds--code--row="">curl 'https://admin.atlassian.com/gateway/api/users/SERVICE_ACCOUNT_ID/manage/avatar' \
</span><span data-testid="renderer-code-block-line-2" data-ds--code--row="">  -X 'PUT' \   
</span><span data-testid="renderer-code-block-line-3" data-ds--code--row="">  -H&nbsp;'Authorization: Bearer OrgAdminToken' \<br>  -F file=@botavatar.png</span>

💡

You'll find the Service Account ID in the url when you're viewing the Service Account:

https://admin.atlassian.com/o/{org-id}/service-accounts/SERVICE_ACCOUNT_ID

Note that you need an Organisation Admin Token.

💡

That's the Service Account all set. But how do we actually use it?

Up next:

Part 3: Atlassian Service Accounts in Practice

And in case you missed it. Part 1: What are they (for)
And check out Part 4: Token renewal

Comments

Gerusa Lobo

Hi @Rebekka Heilmann _viadee_ ,

I've tried test atlassian service accounts, but I have a some difficult.

Mainly with Basic conections. We only have a success with Assets API, but in Jira and Confluence API's the connection was have a 401 error response.

It is like the scope is not working properly or it works only to OAuth2 authentication.

Could you have any tips about it?

Thanks in advance.

Rebekka Heilmann (viadee)

@Gerusa Lobo wait for Part 3, which will most likely be published tomorrow.

Dave LIAO

@Rebekka Heilmann _viadee_ - Yes! Tracking service accounts in a Confluence Database or in Assets is a must!

Not tracking is a recipe for confusion. 🙂‍↔️
Tracking on a single page becomes unwieldy. 🥲
At a minimum, I suggest that admins store the related Jira request ID in the service account's description field. (Service accounts have associated Jira request's, right? 😅😅😅)

Dave LIAO

@Gerusa Lobo - part 3 of this series is here! 🙌

Chris

Hi @Rebekka Heilmann _viadee_ ,

I am trying to use a service account to access Assets data. I am struggling with the correct scope, as Assets is not mentioned in the scope list at all. Could you elaborate on this? Which scope do I have to choose? What is the correct endpoint to access Assets data?

Thank you

Rebekka Heilmann (viadee)

Hi @Chris

not sure but have you tried using the scopes from that documentation? Assets scopes for OAuth 2.0 (3LO) and Forge apps I can find those scopes when creating a token so assume it should be working.

url would look something like https://api.atlassian.com/ex/jira/{cloudId}/jsm/assets/workspace/{workspaceId}/v{version}/object/{id}

Caleb Olson

@Rebekka Heilmann _viadee_ are there any plans to allow rotating service account api tokens without having to re-select all the same scopes/permissions? We have a fairly complex integration with Jira that requires a mix of scopes, and it's a pain to have to search for and select each scope every time the api token expires.. Ideally the permission object is separate from the actual api key, allowing for fixed permissions and ease of rotation.

EDIT: we do store a list of all granted scopes so we don't accidentally revoke a needed scope when rotating (or grant an unnecessary one), though I can't help but feel this process is unnecessarily cumbersome. I've interacted with plenty of other systems in my time that allow for the style of key rotation I'm describing here. We know the key expiry can be set to one year to lessen this burden, but we mandate a maximum TTL of 90 days for all credentials at our org, so we're stuck bothering with this flow every 3 months.

Angelica Pauli

Hi @Rebekka Heilmann _viadee_ - Do you recommend using multiple service accounts to access different spaces?

Jonas Nilsson _ Unitlane

One thing I would add for admins is that service accounts need an explicit exception policy, not just documentation. They often look inactive in the human sense, but that is normal when they authenticate through tokens instead of interactive login.

If you do not separate them from normal cleanup logic, they become false positives in access reviews and license cleanup.

Rebekka Heilmann (viadee)

Hi @Caleb Olson - welcome to the Community,

I haven't heard of anything around that but found a feature request for rotating API Tokens: https://jira.atlassian.com/browse/ID-807. I've just added a comment there and you can too, to raise urgency

Rebekka Heilmann (viadee)

Hi @Angelica Pauli - welcome to the Community,

without knowing the specific setup, I'd say limiting each Service Account to only one or a few spaces, adds a certain level of Security. Even if a Token is compromised, they will only have access to those limited spaces (if the token scope allows it).

If you had one Service Account that is added to 100 Team Spaces and each Team has their own token, then the one token still grants access to all 100 Spaces. So one comprised token gives access to a lot of information.

That said, you need to also consider the size of the Company and needed Service Accounts - if you have one per Space, that adds up quickly

I'd generally recommend one Service Account per Team (or big Use Case) and multiple distinctive tokens with limited scopes. That way, the Team can control Space access (as they tend to be Space Admins anyway) and one compromised token (or Account) doesn't give access to everything.

Another note: Make sure that Service Accounts are NOT added to any global groups that are granted Space permissions per default, especially for sensitive information.

Rebekka Heilmann (viadee)

Hi @Jonas Nilsson _ Unitlane

yes! I've not tested whether Service Accounts come up in the normal User APIs but would think that they are not part of those lists. So any jobs that use the regular "list users" function and check for activity should be fine.

I feel like that is one reason for Service Accounts: to not have "normal" user accounts that look inactive when in reality they are. You can check token activity in the Service Account section in Administration (or in the API token section for normal users)

Saša Pupovac

Hi @Rebekka Heilmann _viadee_ ,

Great work on this 3 part series.

Is there any plan to have service account creation and credentials rerolling be made available by means of REST API requests. In the best case, we would have this available as a self service type of solution in Atlassian Forge.

Rebekka Heilmann (viadee)

Hi @Saša Pupovac

there are a number of feature requests around this e.g. https://jira.atlassian.com/browse/AX-1778

You can search JAC and watch the requests. As this is still a fairly new feature, I expect at least some improvements this year but there is no public roadmap.

Matthias Gaiser _K15t_

Hey @Rebekka Heilmann _viadee_,

thanks again for your detailed breakdown.

You wrote:

Don’t mix granular with classic token scopes

Can you elaborate why you recommend that? From my app development perspective, there's no actual drawback in using classic scopes to cover the basic scope need and add granular scopes as needed. So, I'd appreciate your reasoning for that.

Gerusa Lobo

Hi @Matthias Gaiser _K15t_

I my experience, We could mix both scope types, but for different applications.

For exemple:

To read jira issues and assets:

Read
read:cmdb-attribute:jira
read:cmdb-icon:jira
read:cmdb-object:jira
read:cmdb-schema:jira
read:cmdb-type:jira
read:servicedesk-request
read:jira-user
read:jira-work

Besides, the scope, the service account needs the permission on the projects.

And the url for the API calls are different, start as:

"<a href="https://api.atlassian.com/ex/jira/" target="_blank" rel="nofollow noopener noreferrer">https://api.atlassian.com/ex/jira/</a><cloudId>/rest/api/3/<resource-name>

For example, <a href="https://api.atlassian.com/ex/jira/35273b54-3f06-40d2-880f-dd28cf8daafa/rest/api/3/issue/DEMO-1" target="_blank" rel="nofollow noopener noreferrer">https://api.atlassian.com/ex/jira/35273b54-3f06-40d2-880f-dd28cf8daafa/rest/api/3/issue/DEMO-1</a>"

Rebekka Heilmann (viadee)

Hi @Matthias Gaiser _K15t_

to be honest, this is based on recommendations from some Devs in my network in the early days of Service Accounts. If you're telling me, there is no drawbacks and have tested that with Service Accounts as well, I am happy to update the article.

The series consolidates knowledge of multiple people and testing I've done, but I've not used Service Accounts (or the API for that matter) on large scale.

Matthias Gaiser _K15t_

Thank you for the explanation @Rebekka Heilmann _viadee_.

In various documentations, e.g. the Jira scopes, Atlassian recommends:

When choosing your scopes, the recommendation is to use classic scopes.

That's also my experience and recommendation. If possible, use classic scopes. If some endpoints require explicitly a granular scope, also add that one.

That's what we've applied in app development, but it also seems to be valid for service accounts (based on my tests).

Gerusa Lobo

Hi @Matthias Gaiser _K15t_ and @Rebekka Heilmann _viadee_ ,

In my experience, when we don't have a classic scope for application or module, I usually selected all granular scopes for read or write.

For exemple: Assets.

The granular scopes for assets starts with cmdb

Besides the API indicates a few granular scopes to read a endpoint, in my tests, it is not work properly.

So I need select all read.cmdb granular scopes, and than, It works.

Rebekka Heilmann (viadee)

Updated

Rebekka Heilmann (viadee)

I've just updated the article to reflect new information that I've published in Part 4: Token renewal

Managing Service Accounts have gotten a lot easier!

Chris Bezile

Very interesting and helpful articles! I'm struggling with adding the Service Account to a Confluence space. I go into Space Settings / Users / Add People and I can find every regular user in my org, but when I search for the name of the Service Account nothing shows up. How can I add the Service Account as a user to a Confluence space so I can assign specific permissions?

Rebekka Heilmann (viadee)

@Chris Bezile does the Service User have Confluence access set up in the Administration? That would be the first thing I'd check.

Chris Bezile

@Rebekka Heilmann _viadee_ Yes, the service account has user access to Confluence. It just doesn't show up in the list when I attempt to "Add User" within a specific Confluence space.

Rebekka Heilmann (viadee)

that's not the expected behaviour for sure. you could either open up a question here in the forum so we can troubleshoot there or open a support request and the Atlassian team can look into it.

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

rest-api

api

administration

organization-administration

service-account