> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/ticketing-and-messaging/ticket-management/jira/connecting-jira/connecting-jira-with-a-service-account-oauth-2.0.md).

# Connecting Jira with a Service Account (OAuth 2.0)

OAuth 2.0 is the industry-standard framework for secure system-to-system access between apps, and the authentication type Atlassian recommends for service accounts.

Connecting OX to Jira through an OAuth 2.0 service account gives you all the benefits of the service account model, an organization-owned identity that survives staff changes with a credential exchange that does not rely on a long-lived API token.

Compared to the **API token** service account method, OAuth 2.0:

* **Is more secure:** The Client ID and Client Secret are used to obtain short-lived access tokens at runtime rather than presenting a long-lived bearer token on every request.
* **Is the Atlassian-recommended authentication type:** Marked as **Recommended** by Atlassian on the *Choose authentication type* step when you create a service account credential.
* **Uses the same app role and scopes as the API token method:** The Jira **User** role plus `read:jira-user`, `read:jira-work`, and `write:jira-work` — the setup on the Atlassian side is identical until the credentials step.

{% hint style="info" %}
If you already connected this Jira site to OX using a [service account with an API token](https://claude.ai/cowork/jira-service-account.md), you can switch to OAuth by creating a new OAuth credential on the same service account and updating the connector in OX. The service account itself, its app role, and any existing scopes do not need to be re-created.
{% 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 OAuth credentials \[Jira]

1. Sign in to the [Atlassian Admin](https://admin.atlassian.com/) console.

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

2. Open your organization and go to **Directory > Service accounts**.

<figure><img src="/files/xYS7RdCSCOJwFSlm1Su3" alt="" width="268"><figcaption></figcaption></figure>

3. In the top-right corner, select **Create a service account**.
4. Select **Name service account**.

   <table><thead><tr><th width="211.6666259765625">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. 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.
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. If you need project-level permissions beyond the defaults, add the service account to a Jira group that has the appropriate [Jira permissions](https://claude.ai/cowork/jira-permissions.md).
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.
12. In the top-right corner, select **Create credentials**.

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

13. In the **Choose authentication type** dialog, select **OAuth 2.0**, and then select **Next**.

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

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

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

| Field    | What to use                                        |
| -------- | -------------------------------------------------- |
| **Name** | A meaningful identifier (for example, `ox-oauth`). |

15. Select **Next**.
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:

    <table><thead><tr><th width="203.3333740234375">Scope</th><th>Purpose</th></tr></thead><tbody><tr><td><code>read:jira-user</code></td><td>View user information in Jira (username, email, avatar) for assigning issues and resolving reporters.</td></tr><tr><td><code>read:jira-work</code></td><td>Read Jira project and issue data, search for issues, and read related objects (attachments, worklogs, etc.).</td></tr><tr><td><code>write:jira-work</code></td><td>Create and edit Jira issues, post comments, create worklogs, and (where allowed) delete issues.</td></tr></tbody></table>
18. Select **Next**.
19. In the **Create credential** dialog, review the name and scopes.
20. Select **Create**, and then copy the **Client ID** and **Client Secret** immediately and store them in a secure location. The Client Secret is shown only once.

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

### 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**.

<figure><img src="/files/DnbWYuYI8sEwqVWHM8p6" alt="" width="493"><figcaption></figcaption></figure>

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

| Field               | What to use                                                                  |
| ------------------- | ---------------------------------------------------------------------------- |
| **Client ID**       | The Client ID you copied in Step 1.                                          |
| **Client Secret**   | The Client Secret you copied in Step 1.                                      |
| **Connection Name** | A label for this connection (for example, `Jira Service Account OAuth 001`). |

Leave [**OX Broker**](/get-started/onboarding-to-ox/prerequisites-and-access/ox-broker.md) off and **Bypass SSL Verification** unchecked unless your environment specifically requires them.

3. Select **CONNECT**. OX validates the credentials and the success message appears.

### [Step 4: Add Jira tickets](https://claude.ai/cowork/jira.md#adding-jira-tickets)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.