# Connecting Jira with a Service Account

A service account is an Atlassian identity that belongs to your organization rather than to an individual user. Connecting OX to Jira through a service account is the recommended authentication method for the OX Jira connector and the approach Atlassian itself encourages for system-to-system integrations.

Compared to the personal API token method, a service account:

* **Stays with the organization, not the employee:** The credential keeps working when the person who set up the integration leaves the team.
* **Is more secure:** Permissions are scoped narrowly to what OX needs (a single app role and a small set of API token scopes), and the credential is auditable as a non-human identity.
* **Is the Atlassian-recommended pattern:** For automations and third-party integrations such as OX.

{% hint style="info" %}
The personal **username + token** method is still supported, but new integrations should use a service account where possible.
{% endhint %}

### Prerequisites

* An Atlassian organization with **Organization admin** access to the [Atlassian Admin](https://admin.atlassian.com/) console.

## Step 1: Create a service account and generate a token \[Jira]

1. Sign in to the [Atlassian Admin](https://admin.atlassian.com/) console.
2. Open your organization and go to **Directory > Service accounts**.
3. In the top-right corner, select **Create a service account**.

<figure><img src="/files/YYDMiWBVFhmUElrJYbk7" alt="" width="563"><figcaption></figcaption></figure>

4. Select **Name service account**.

<figure><img src="/files/sBoDhaHg5HfDnJEFkptZ" alt="" width="563"><figcaption></figcaption></figure>

<table><thead><tr><th width="171.5">Field</th><th>What to use</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td>A descriptive, organization-level name (for example, <code>Ox-Service-Account</code>). 6–30 characters.<br>Atlassian uses the name to generate a unique service account email of the form <code>&#x3C;name>-&#x3C;random>@serviceaccount.atlassian.com</code>.</td></tr><tr><td><strong>Description</strong></td><td>The purpose of the account (for example, <code>Ox Security Integration account</code>).</td></tr></tbody></table>

5. Select **Next**.
6. On the top, select **Assign an app role**.

> **Note:** The process of assigning an app role is intended for choosing the minimum permissions required for the OX integration.

7. In the apps list, locate the **Jira** row.
8. In the **Roles** column, open the dropdown and select **User**. This is the only role OX requires.

<figure><img src="/files/vWO93GjwH24nTKHXnz51" alt="" width="563"><figcaption></figcaption></figure>

9. Leave all other apps (for example, Goals, Projects, Confluence, Jira Administration) set to **None** unless you have a specific reason to grant them.
10. Leave **Groups** empty unless your organization uses customized groups to grant access to specific projects or spaces.
11. Select **Create**. The service account is created and its detail page appears; the generated email identifies the account but is not used in the OX connector form.

<figure><img src="/files/nWbezDJsnbzF23Fmvr7z" alt="" width="563"><figcaption></figcaption></figure>

12. In the top-right corner, select **Create credentials**.
13. In the **Choose authentication type** dialog, select **API token**, and then select **Next**.

<figure><img src="/files/yUqgyX0FZEbo9eA3jtRV" alt="" width="563"><figcaption></figcaption></figure>

14. In the **Name token** step, set the following:

| Field          | What to use                                                                          |
| -------------- | ------------------------------------------------------------------------------------ |
| **Name**       | A meaningful identifier (for example, `Ox-api-token`).                               |
| **Expires on** | Optional. Defaults to 1 year. Set to the longest period your security policy allows. |

15. Select **Next**.

<figure><img src="/files/EFN2FiD5AQ1qhroImpgN" alt="" width="563"><figcaption></figcaption></figure>

16. In the **Select scopes** dialog, filter the list so it only shows the scopes OX needs:

* **App** filter: select **Jira**.
* **Scope type** filter: select **Classic**.
* **Scope actions** filter: select **Read** and **Write**.

17. From the filtered results, select the following three scopes:

| Scope             | Purpose                                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------ |
| `read:jira-user`  | View user information in Jira (username, email, avatar) for assigning issues and resolving reporters.        |
| `read:jira-work`  | Read Jira project and issue data, search for issues, and read related objects (attachments, worklogs, etc.). |
| `write:jira-work` | Create and edit Jira issues, post comments, create worklogs, and (where allowed) delete issues.              |

18. Select **Next**.
19. In the **Create token** dialog, review the name, expiration date, and scopes.

<figure><img src="/files/Q91BElbcSCUZEcVWMare" alt="" width="563"><figcaption></figcaption></figure>

20. Select **Create**, and then copy the token immediately and store it in a secure location. The API token is shown only once.

### Step 2: Find your Jira Cloud ID \[Jira]

When you authenticate as a service account, the Jira Host URL that OX uses is different from the URL used with the personal username + token method. It points at Atlassian's gateway endpoint and is keyed by your Cloud ID:

```
https://api.atlassian.com/ex/jira/<cloudId>
```

Use either of the following self-service methods. Both are documented by Atlassian in [How to Find Your Atlassian Cloud Site's Cloud ID](https://support.atlassian.com/jira/kb/retrieve-my-atlassian-sites-cloud-id/).

**Option A: From the Atlassian Admin URL**

1. Go to [admin.atlassian.com](https://admin.atlassian.com/) and, if prompted, select the relevant **Organization**.
2. From the main navigation, select **Products**.
3. Under **Sites and products**, select the Jira site you are connecting.
4. Look at the browser address bar. The Cloud ID is the value that appears after `/s/`, for example:

   ```
   https://admin.atlassian.com/s/<your_cloud_id>/access-requests
   ```

**Option B: From the `tenant_info` endpoint**

1. While signed in to your Jira site, open the following URL in a new tab:

   ```
   https://<your-site>.atlassian.net/_edge/tenant_info
   ```

   Replace `<your-site>` with the subdomain you use to access Jira (for example, `acme` for `https://acme.atlassian.net`).
2. The page returns a JSON document similar to:

   ```json
   { "cloudId": "18cd6e54-b562-4ed3-8a43-ca1fc772b26f" }
   ```
3. Copy the `cloudId` value.

{% hint style="info" %}
The **Cloud ID** is not the same as your **Organization ID**. The Organization ID identifies a grouping of sites and products in Atlassian Admin and is not used by the OX Jira connector.
{% endhint %}

### Step 3: Connect Jira to OX

1. In the **OX app**, go to **Connectors** and search for **Jira**.
2. Select **Jira.**

<figure><img src="/files/PXkxoByy5XKvd6vt4n1C" alt="" width="500"><figcaption></figcaption></figure>

3. Select the **Service Account** tab and set the following parameters in the **Configure your Jira credentials** dialog:

   | Field               | What to use                                                                                                           |
   | ------------------- | --------------------------------------------------------------------------------------------------------------------- |
   | **Jira Host URL**   | `https://api.atlassian.com/ex/jira/<cloudId>` using the Cloud ID from [Step 2](#step-2-find-your-jira-cloud-id-jira). |
   | **Token**           | The API token you copied in [Step 1](#step-1-create-a-service-account-and-generate-a-token-jira).                     |
   | **Connection Name** | A label for this connection (for example, `Jira Service Account Name 001`).                                           |
4. Leave [**OX Broker** ](/get-started/onboarding-to-ox/prerequisites-and-access/ox-broker.md)off and **Bypass SSL Verification** not selected unless your environment specifically requires them.
5. Select **CONNECT**. OX validates the credentials and the success message appears.

## [Step 4: Add Jira tickets](/ticketing-and-messaging/ticket-management/jira/adding-jira-tickets.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ox.security/ticketing-and-messaging/ticket-management/jira/connecting-jira-with-a-service-account.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.