Skip to content

Commit bc6b1b2

Browse files
waleedlatif1waleedlatif1
authored
fix(search): clarify Atlassian setup and validate Confluence permissions (#7722)
* fix(search): clarify Atlassian setup and validate Confluence permissions * chore(docs): clarify Confluence setup permission sampling
1 parent ae02d86 commit bc6b1b2

19 files changed

Lines changed: 789 additions & 361 deletions

File tree

‎apps/docs/content/docs/integrations/atlassian-service-account.mdx‎

Lines changed: 68 additions & 144 deletions
Original file line numberDiff line numberDiff line change
@@ -1,177 +1,101 @@
11
---
22
title: Atlassian Service Accounts
3-
description: Set up an Atlassian service account with a scoped API token to use Jira, Jira Service Management, and Confluence in Sim workflows
3+
description: Connect Jira, Jira Service Management, and Confluence workflows with a scoped service-account API token
44
---
55

66
import { Callout } from 'fumadocs-ui/components/callout'
7-
import { Step, Steps } from 'fumadocs-ui/components/steps'
87
import { Image } from '@/components/ui/image'
9-
import { FAQ } from '@/components/ui/faq'
10-
11-
Use an Atlassian service account with a scoped API token to connect Jira, Jira Service Management, and Confluence. Grant the account access to the products, projects, and spaces your workflows need.
128

9+
Use an Atlassian service account for Jira, Jira Service Management, and Confluence workflows. One credential can serve all three products on the same site when its account access and token scopes cover each product.
1310

11+
<Callout type="info">
12+
Setting up Search? Follow the [Confluence Search service-account guide](/search/confluence#using-a-service-account) for its content and permission scopes. [Jira Search](/search/jira) uses each teammate's OAuth account; a workflow service account does not replace that connection.
13+
</Callout>
1414

15-
One service account covers all three products. You add it once, and it appears as a connected credential on the Jira, Jira Service Management, and Confluence integration pages alike — there is no separate credential to create per product.
15+
## Create the account and token
1616

17-
## Prerequisites
17+
An **Atlassian organization admin** completes these steps:
1818

19-
You need an Atlassian organization admin to create the service account. Service accounts are an Atlassian organization-level feature — they cannot be created from a regular user account.
19+
1. Open [Atlassian Administration](https://admin.atlassian.com/), select the organization, then **Directory → Service accounts → Create service account**.
20+
2. Give the account access to the intended site's Jira and/or Confluence apps. Grant the project and space permissions its workflows need, including access to restricted content.
21+
3. Select the service account, then **Create credentials → API token → Next**.
22+
4. Name the token, set an expiry between 1 and 365 days, and select **Next**.
23+
5. Select the scopes below for the products and operations you need. Review and create the token, then copy it. Atlassian shows it only once.
2024

21-
## Setting Up the Service Account
25+
See Atlassian's [service-account setup](https://support.atlassian.com/user-management/docs/manage-your-service-accounts/) and [token instructions](https://support.atlassian.com/user-management/docs/manage-api-tokens-for-service-accounts/).
2226

23-
### 1. Create the Service Account
27+
<Image className="mx-auto h-auto w-full max-w-md"
28+
src="/static/credentials/atlassian/admin-auth-type-picker.png"
29+
alt="Atlassian Administration credential selector with API token selected"
30+
width={700}
31+
height={551}
32+
/>
2433

25-
<Steps>
26-
<Step>
27-
Open [admin.atlassian.com](https://admin.atlassian.com/) and go to **Directory** → **Service accounts**
34+
## Choose scopes
2835

29-
{/* TODO(screenshot): admin.atlassian.com directory page with the "Service accounts" tab highlighted */}
30-
</Step>
31-
<Step>
32-
Click **Create service account**, give it a name (e.g. `sim-jira-bot`), and finish creation
33-
</Step>
34-
<Step>
35-
Grant the service account access to the Atlassian sites and products it needs. Open the service account, go to **Product access**, and add Jira and/or Confluence on the relevant site
36+
Start with the connection and read scopes for each product you will use. These cover Sim's account validation, pickers, and common read operations; individual operations may need additional scopes.
3637

37-
{/* TODO(screenshot): service account "Product access" tab showing Jira granted on a site */}
38-
</Step>
39-
</Steps>
38+
### Jira and Jira Service Management
4039

41-
<Callout type="info">
42-
The service account inherits permissions from the project/space roles you grant it — exactly like a human user. If a workflow needs to write to a specific Jira project, give the service account write access to that project in Jira's project settings.
43-
</Callout>
40+
```text
41+
read:jira-user
42+
read:jira-work
43+
```
4444

45-
### 2. Create a Scoped API Token
46-
47-
<Steps>
48-
<Step>
49-
From the service account's page in admin.atlassian.com, open the **API tokens** tab and click **Create API token**
50-
51-
{/* TODO(screenshot): service account API tokens tab with "Create API token" button */}
52-
</Step>
53-
<Step>
54-
Choose **API token** as the authentication type (not OAuth 2.0 — Sim uses the API token flow)
55-
56-
<div className="flex justify-center">
57-
<Image
58-
src="/static/credentials/atlassian/admin-auth-type-picker.png"
59-
alt="Atlassian admin — Choose authentication type with API token selected"
60-
width={700}
61-
height={551}
62-
className="my-4"
63-
/>
64-
</div>
65-
</Step>
66-
<Step>
67-
Select the scopes the token needs. The minimum set Sim's Jira and Confluence blocks expect is:
68-
69-
**Jira (classic):**
70-
```
71-
read:jira-user
72-
read:jira-work
73-
write:jira-work
74-
```
75-
76-
**Jira Service Management (classic):**
77-
```
78-
read:servicedesk-request
79-
write:servicedesk-request
80-
manage:servicedesk-customer
81-
```
82-
83-
**Confluence (classic and granular):**
84-
```
85-
read:confluence-content.all
86-
read:confluence-space.summary
87-
write:confluence-content
88-
read:page:confluence
89-
write:page:confluence
90-
```
91-
92-
Add more scopes only if you need the corresponding operations (delete, manage webhooks, etc.). The full list of scopes Sim's blocks may use is documented in [Atlassian's developer reference](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/).
93-
94-
<Callout type="warn">
95-
Prefer the classic scopes above over granular equivalents. Atlassian enforces an endpoint's granular scope list as all-or-nothing, so a token built from a partial granular set fails with `Unauthorized; scope does not match` even though each individual scope was granted. The classic scopes each cover their product's endpoints on their own. If your organization only permits granular scopes, include every scope listed for each endpoint in Atlassian's reference — Jira Service Management request operations also require `read:user:jira`.
96-
</Callout>
97-
98-
<div className="flex justify-center">
99-
<Image
100-
src="/static/credentials/atlassian/admin-scope-picker.png"
101-
alt="Atlassian token scope picker filtered to App: Jira and Scope type: Classic"
102-
width={1000}
103-
height={635}
104-
className="my-4"
105-
/>
106-
</div>
107-
108-
<Callout type="info">
109-
Use the **App** and **Scope type** filters to narrow the list to the scopes you need. Filter by `App: Jira` (or `Confluence`) and `Scope type: Classic` to find the three core Jira scopes; switch to **Granular** if your org doesn't expose Classic.
110-
</Callout>
111-
</Step>
112-
<Step>
113-
Copy the token when it is shown and record its expiration date in Atlassian Administration. Create a replacement before it expires; Sim does not refresh a pasted API token.
114-
</Step>
115-
</Steps>
116-
117-
<Callout type="warn">
118-
The API token is bearer credentials for the service account. Treat it like a password — do not commit it to source control or share it publicly. Sim encrypts the token at rest.
119-
</Callout>
45+
`read:jira-user` covers the [current-user check](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-myself/#api-rest-api-3-myself-get) when you add the credential, including through Jira Service Management. Add `read:servicedesk-request` for Service Management requests.
12046

121-
### 3. Find Your Site Domain
47+
### Confluence
12248

123-
Enter only the host from your Jira or Confluence URL, such as `your-team.atlassian.net`; omit `https://` and any path.
49+
```text
50+
read:confluence-user
51+
read:confluence-content.all
52+
read:confluence-space.summary
53+
read:space:confluence
54+
read:page:confluence
55+
```
12456

125-
## Adding the Service Account to Sim
57+
`read:confluence-user` covers the [current-user check](https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-users/#api-wiki-rest-api-user-current-get). The [space picker](https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-space/#api-spaces-get) needs `read:space:confluence`; page reads and the page picker need `read:page:confluence`.
12658

127-
<Steps>
128-
<Step>
129-
Open **Integrations** in your workspace sidebar
130-
</Step>
131-
<Step>
132-
Open **Jira**, **Jira Service Management**, or **Confluence** — any of the three works, since they share one service account
59+
### Workflow actions
13360

134-
{/* TODO(screenshot): Integrations page with Jira in the list */}
135-
</Step>
136-
<Step>
137-
Click **Add to Sim** and choose **Add service account**
61+
Add scopes for the actions your workflow performs:
13862

139-
{/* TODO(screenshot): Jira integration page with the "Add to Sim" dropdown open */}
140-
</Step>
141-
<Step>
142-
Paste the API token, enter the site domain (e.g. `your-team.atlassian.net`), and optionally set a display name and description
63+
| Actions | Scopes to add |
64+
| --- | --- |
65+
| Create or update Jira issues | `write:jira-work` |
66+
| Create or update Service Management requests | `write:servicedesk-request` |
67+
| Manage Service Management customers | `manage:servicedesk-customer` |
68+
| Create or update Confluence content | `write:confluence-content`, `write:page:confluence` |
14369

70+
Delete, webhook, Assets, and other operations can require additional scopes. Check the specific endpoint in the [Jira](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/), [Jira Service Management](https://developer.atlassian.com/cloud/jira/service-desk/rest/intro/), or [Confluence](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/) API reference. Include the complete scope set for that endpoint; a classic scope does not cover every API in its product.
14471

145-
</Step>
146-
<Step>
147-
Click **Add service account**. Sim resolves the site and checks the token against the selected product's identity endpoint. Review any connection error before continuing.
148-
</Step>
149-
</Steps>
72+
Use the **App** and **Scope type** filters to find both classic and granular scopes. Scopes and account permissions are separate: the account must also have access to the project, space, or content.
15073

151-
The token, domain, and discovered cloudId are encrypted before being stored.
74+
<Image className="mx-auto h-auto w-full max-w-xl"
75+
src="/static/credentials/atlassian/admin-scope-picker.png"
76+
alt="Atlassian scope picker filtered to Jira classic scopes"
77+
width={1000}
78+
height={635}
79+
/>
15280

153-
Once added, the credential is listed under **Connected** on all three Atlassian integration pages. It is named after the service account's own Atlassian display name, so several service accounts on the same site stay easy to tell apart.
81+
## Add the credential to Sim
15482

155-
## Using the Service Account in Workflows
83+
1. Open **Integrations** in your workspace sidebar, then **Jira**, **Jira Service Management**, or **Confluence**.
84+
2. Select **Add to Sim → Add service account**. If only service accounts are available, select **Add service account** directly.
85+
3. Paste the **API token** and enter **Site domain**, such as `your-team.atlassian.net`. Omit `https://` and any path. Optionally add a display name and description.
86+
4. Select **Add service account**. Sim checks the token against the selected product's current-user endpoint; resolve any error before continuing.
87+
5. In your workflow's Jira, Jira Service Management, or Confluence block, select the credential and configure the operation.
15688

157-
Add a Jira, Jira Service Management, or Confluence block to your workflow. In the credential dropdown, your Atlassian service account appears alongside any OAuth credentials. Select it and configure the block as you normally would.
89+
The credential appears on all three integration pages, but adding it only validates the selected product. Check account access and scopes before using another product. Sim encrypts the token at rest and calls Atlassian as the service account.
15890

159-
<div className="flex justify-center">
160-
<Image
161-
src="/static/credentials/atlassian/sim-jira-block-credential.png"
162-
alt="Jira block in a workflow with the Atlassian service account selected as the credential"
163-
width={1000}
164-
height={584}
165-
className="my-4"
166-
/>
167-
</div>
91+
## Troubleshooting and rotation
16892

169-
The block calls Atlassian's API gateway (`api.atlassian.com/ex/jira/{cloudId}/...`) using the service account's token. There's no impersonation step — the service account acts as itself, with whatever permissions you granted it in admin.atlassian.com.
93+
| Problem | What to check |
94+
| --- | --- |
95+
| Cannot add the credential | Use a scoped API token from **Directory → Service accounts**, verify its expiry and site, and include the selected product's current-user scope above. |
96+
| Empty or failed picker | Include `read:jira-work` for Jira projects or `read:space:confluence` for Confluence spaces, and grant the account access to the selected site and content. |
97+
| A workflow returns a scope or permission error | Check the operation's full scope list and the account's project/space permissions. Successful connection does not validate every operation. |
98+
| Token expires or needs different scopes | Create a replacement token, add it as a new Sim service-account credential, and select it in the affected workflows. Test them before revoking the old token. Sim does not refresh pasted API tokens. |
99+
| Data Center or Server host | This credential supports Atlassian Cloud only. |
170100

171-
<FAQ items={[
172-
{ question: "Can a regular user create a service account?", answer: "No. Service accounts are an Atlassian organization-level feature and only an organization admin can create them." },
173-
{ question: "Can the same service account work with Jira, Jira Service Management, and Confluence?", answer: "Yes — one service account covers all three. Give it access to each product you need on your site, include scopes for each when you create the API token, then connect it once in Sim. It appears as a connected credential on all three integration pages and can be selected from any of their blocks." },
174-
{ question: "What if my workflow needs different permissions than the token has?", answer: "Either widen the token's scopes (revoke it and create a new one with more scopes), or grant the service account higher project/space roles in Jira or Confluence. Scope failures look like 401/403 errors with descriptive messages." },
175-
{ question: "How do I rotate the API token?", answer: "Create a new token from the same service account in admin.atlassian.com, update the credential in Sim with the new token, and once it's working, revoke the old one." },
176-
{ question: "Does this work with Atlassian Data Center / on-prem?", answer: "No. This credential supports Atlassian Cloud through api.atlassian.com. It cannot connect to an Atlassian Data Center host." },
177-
]} />
101+
For a Search source, follow [Confluence's indexing-account replacement steps](/search/confluence#using-a-service-account).

0 commit comments

Comments
 (0)