|
| 1 | +--- |
| 2 | +title: Atlassian Service Accounts |
| 3 | +description: Set up an Atlassian service account with a scoped API token to use Jira and Confluence in Sim workflows |
| 4 | +--- |
| 5 | + |
| 6 | +import { Callout } from 'fumadocs-ui/components/callout' |
| 7 | +import { Step, Steps } from 'fumadocs-ui/components/steps' |
| 8 | +import { Image } from '@/components/ui/image' |
| 9 | +import { FAQ } from '@/components/ui/faq' |
| 10 | + |
| 11 | +Atlassian service accounts let your workflows authenticate to Jira and Confluence as a non-human bot user — independent of any individual employee's account. Each service account has its own email, its own permissions, and its own API tokens, all managed centrally in admin.atlassian.com. |
| 12 | + |
| 13 | +This is the recommended way to use Jira and Confluence in production workflows: no one person's OAuth consent expires, the bot's permissions are auditable, and access can be revoked without touching anyone's personal account. |
| 14 | + |
| 15 | +## Prerequisites |
| 16 | + |
| 17 | +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. |
| 18 | + |
| 19 | +## Setting Up the Service Account |
| 20 | + |
| 21 | +### 1. Create the Service Account |
| 22 | + |
| 23 | +<Steps> |
| 24 | + <Step> |
| 25 | + Open [admin.atlassian.com](https://admin.atlassian.com/) and go to **Directory** → **Service accounts** |
| 26 | + |
| 27 | + {/* TODO(screenshot): admin.atlassian.com directory page with the "Service accounts" tab highlighted */} |
| 28 | + </Step> |
| 29 | + <Step> |
| 30 | + Click **Create service account**, give it a name (e.g. `sim-jira-bot`), and finish creation |
| 31 | + </Step> |
| 32 | + <Step> |
| 33 | + 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 |
| 34 | + |
| 35 | + {/* TODO(screenshot): service account "Product access" tab showing Jira granted on a site */} |
| 36 | + </Step> |
| 37 | +</Steps> |
| 38 | + |
| 39 | +<Callout type="info"> |
| 40 | +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. |
| 41 | +</Callout> |
| 42 | + |
| 43 | +### 2. Create a Scoped API Token |
| 44 | + |
| 45 | +<Steps> |
| 46 | + <Step> |
| 47 | + From the service account's page in admin.atlassian.com, open the **API tokens** tab and click **Create API token** |
| 48 | + |
| 49 | + {/* TODO(screenshot): service account API tokens tab with "Create API token" button */} |
| 50 | + </Step> |
| 51 | + <Step> |
| 52 | + Choose **API token** as the authentication type (not OAuth 2.0 — Sim uses the API token flow) |
| 53 | + |
| 54 | + <div className="flex justify-center"> |
| 55 | + <Image |
| 56 | + src="/static/credentials/atlassian/admin-auth-type-picker.png" |
| 57 | + alt="Atlassian admin — Choose authentication type with API token selected" |
| 58 | + width={700} |
| 59 | + height={500} |
| 60 | + className="my-4" |
| 61 | + /> |
| 62 | + </div> |
| 63 | + </Step> |
| 64 | + <Step> |
| 65 | + Select the scopes the token needs. The minimum set Sim's Jira and Confluence blocks expect is: |
| 66 | + |
| 67 | + **Jira (granular):** |
| 68 | + ``` |
| 69 | + read:jira-user |
| 70 | + read:jira-work |
| 71 | + write:jira-work |
| 72 | + ``` |
| 73 | + |
| 74 | + **Confluence (granular):** |
| 75 | + ``` |
| 76 | + read:confluence-content.all |
| 77 | + read:confluence-space.summary |
| 78 | + write:confluence-content |
| 79 | + read:page:confluence |
| 80 | + write:page:confluence |
| 81 | + ``` |
| 82 | + |
| 83 | + 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/). |
| 84 | + |
| 85 | + <div className="flex justify-center"> |
| 86 | + <Image |
| 87 | + src="/static/credentials/atlassian/admin-scope-picker.png" |
| 88 | + alt="Atlassian token scope picker filtered to App: Jira and Scope type: Classic" |
| 89 | + width={1000} |
| 90 | + height={600} |
| 91 | + className="my-4" |
| 92 | + /> |
| 93 | + </div> |
| 94 | + |
| 95 | + <Callout type="info"> |
| 96 | + 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. |
| 97 | + </Callout> |
| 98 | + </Step> |
| 99 | + <Step> |
| 100 | + Copy the token when it's shown. Atlassian only displays it once — if you close the dialog, you'll have to create a new token. |
| 101 | + </Step> |
| 102 | +</Steps> |
| 103 | + |
| 104 | +<Callout type="warn"> |
| 105 | +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. |
| 106 | +</Callout> |
| 107 | + |
| 108 | +### 3. Find Your Site Domain |
| 109 | + |
| 110 | +Your Atlassian site domain is the URL you use to access Jira or Confluence in your browser — for example, `your-team.atlassian.net`. Open Jira or Confluence, look at the address bar, and copy the part before the first `/`. |
| 111 | + |
| 112 | +## Adding the Service Account to Sim |
| 113 | + |
| 114 | +<Steps> |
| 115 | + <Step> |
| 116 | + Open your workspace **Settings** and go to the **Integrations** tab |
| 117 | + </Step> |
| 118 | + <Step> |
| 119 | + Search for "Atlassian Service Account" and click it |
| 120 | + |
| 121 | + {/* TODO(screenshot): Integrations page with "Atlassian Service Account" in the service list */} |
| 122 | + </Step> |
| 123 | + <Step> |
| 124 | + Paste the API token, enter the site domain (e.g. `your-team.atlassian.net`), and optionally set a display name and description |
| 125 | + |
| 126 | + <div className="flex justify-center"> |
| 127 | + <Image |
| 128 | + src="/static/credentials/atlassian/sim-add-modal.png" |
| 129 | + alt="Add Atlassian Service Account dialog with API token and site domain filled in" |
| 130 | + width={420} |
| 131 | + height={560} |
| 132 | + className="my-6" |
| 133 | + /> |
| 134 | + </div> |
| 135 | + </Step> |
| 136 | + <Step> |
| 137 | + Click **Add Service Account**. Sim verifies the token by calling Atlassian's `/myself` endpoint through the gateway — if it fails, you'll see a specific error explaining what went wrong. |
| 138 | + </Step> |
| 139 | +</Steps> |
| 140 | + |
| 141 | +The token, domain, and discovered cloudId are encrypted before being stored. |
| 142 | + |
| 143 | +## Using the Service Account in Workflows |
| 144 | + |
| 145 | +Add a Jira 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. |
| 146 | + |
| 147 | +<div className="flex justify-center"> |
| 148 | + <Image |
| 149 | + src="/static/credentials/atlassian/sim-jira-block-credential.png" |
| 150 | + alt="Jira block in a workflow with the Atlassian service account selected as the credential" |
| 151 | + width={1000} |
| 152 | + height={500} |
| 153 | + className="my-4" |
| 154 | + /> |
| 155 | +</div> |
| 156 | + |
| 157 | +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. |
| 158 | + |
| 159 | +<FAQ items={[ |
| 160 | + { question: "Why an API token instead of OAuth?", answer: "API tokens for service accounts don't have a 1-hour expiry and don't require any user to consent. They're issued by an org admin and are stable until you revoke them — which is what you want for an automated workflow." }, |
| 161 | + { 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." }, |
| 162 | + { question: "Can the same service account work with both Jira and Confluence?", answer: "Yes — give the service account access to both products on your site, and include scopes for both when you create the API token. Then connect it once in Sim and use it from either Jira or Confluence blocks." }, |
| 163 | + { 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." }, |
| 164 | + { 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." }, |
| 165 | + { question: "Does this work with Atlassian Data Center / on-prem?", answer: "No — this integration uses Atlassian Cloud's API gateway (`api.atlassian.com`). For Data Center, use the OAuth flow or set up a self-hosted bot user." }, |
| 166 | +]} /> |
0 commit comments