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

[#1]

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 with Scopes & Expiration date → ⚠️ you cannot check or edit scopes after initial creation

You can use the description field in the Service Account at a minimum. I would recommend setting up something a little more sophisticated, so you can later run checks automatically. Some ideas:

• Confluence table with columns for each info or a page per Service Account
• Confluence databases for Service Accounts and Tokens - you can link each Token to an Account Entry, link Users etc.
• Assets - if you have. You could have Schemes for Users, Teams, Confluence/Jira Spaces, Service Accounts etc. and track ownership of all your Atlassian assets

Rotation and expiry

• Plan for token expiration - any token is valid for 365 days max
• 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

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, new Tokens need to be created at least every year. There is no API support for automated creation but you can provide your users with enough documentation so you at least don’t have to ask for all the details separately.

Consider things like

• A request form for new Accounts
• A request form for App access change
• A request form for new Tokens (listing all the available scopes is a pain in the butt though)
• Automatic renewal of expiring tokens after user confirmation

---

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:

1. 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.”
2. Which products and areas are involved?
   • Jira? Confluence? Which projects/spaces?
3. 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)

1. Go to admin.atlassian.com and select your organization.
2. Open Directory → Service accounts.
3. 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.
4. Give it App access (Jira, Confluence, Goals, … ) in the correct role (User, Customer, App Admin…)
5. 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:

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

💡

Step 3: Create an API Token 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:

1. Go to admin.atlassian.com and select your organization.
2. Go to Directory → Service accounts.
3. Choose the service account → Actions → Create credentials.
4. 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
5. Review and document the scope before creating it.
6. Copy it and store/share it securely (password manager, secret manager, etc.)

💡
Don’t mix granular with classic token scopes. Some granular scopes are not part of any classic scope so they need to be granted specifically.

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/

---

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)

[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.