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.

If you already connected this Jira site to OX using a service account with an API token, 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.

Prerequisites

• An Atlassian organization with Organization admin access to the Atlassian Admin console.

Step 1: Create a service account and generate OAuth credentials [Jira]

1. Sign in to the Atlassian Admin console.

1. Open your organization and go to Directory > Service accounts.

1. In the top-right corner, select Create a service account.

2. Select Name service account.

   Field	What to use
   Name	A descriptive, organization-level name (for example, Ox-Service-Account). 6–30 characters. Atlassian uses the name to generate a unique service account email of the form <name>-<random>@serviceaccount.atlassian.com.
   Description	The purpose of the account (for example, Ox Security Integration account).

3. Select Next.

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

5. In the apps list, locate the Jira row.

6. In the Roles column, open the dropdown and select User. This is the only role OX requires.

7. Leave all other apps (for example, Goals, Projects, Confluence, Jira Administration) set to None unless you have a specific reason to grant them.

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

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

10. In the top-right corner, select Create credentials.

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

1. In the Name credential step, set the following:

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

1. Select Next.

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

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

4. Select Next.

5. In the Create credential dialog, review the name and scopes.

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

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.

Option A: From the Atlassian Admin URL

1. Go to 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:

   { "cloudId": "18cd6e54-b562-4ed3-8a43-ca1fc772b26f" }

3. Copy the cloudId value.

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.

Step 3: Connect Jira to OX

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

1. 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 off and Bypass SSL Verification unchecked unless your environment specifically requires them.

1. Select CONNECT. OX validates the credentials and the success message appears.

Step 4: Add Jira tickets