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.

The personal username + token method is still supported, but new integrations should use a service account where possible.

Prerequisites

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

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

1. Sign in to the Atlassian Admin console.

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

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

1. 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).

1. Select Next.

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

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

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

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

2. Leave Groups empty unless your organization uses customized groups to grant access to specific projects or spaces.

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

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

2. In the Choose authentication type dialog, select API token, and then select Next.

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

1. Select Next.

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

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

1. Select Next.

2. In the Create token dialog, review the name, expiration date, and scopes.

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

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.

2. Select Jira.

1. 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.
   Token	The API token you copied in Step 1.
   Connection Name	A label for this connection (for example, Jira Service Account Name 001).

2. Leave OX Broker off and Bypass SSL Verification not selected unless your environment specifically requires them.

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

Step 4: Add Jira tickets