Overview

Torii integrates with your Jira account and syncs the following attributes:

1. List of users and their roles
2. Usage
3. License type

You can constantly be updated with application information from our Integrations Page >> Integration Capabilities button  >> Integration Capabilities table.

Prerequisites

• At least one user must expose their email address (emailAddress field). If all users’ email addresses are hidden, the integration will fail.
• To get usage data, the user who created the API token must have access to Jira.

Syncing User Roles

We’ve added the ability for the Jira integration to sync user role information. To enable this, you’ll need to provide the following additional fields:

• Atlassian API Key
• Atlassian Organization ID

These fields are optional for the Jira integration. However, they must be provided if you wish to sync users’ roles. For instructions on retrieving these values, please refer to the Atlassian Integration article.

Work Management.

Note: Integration with "Jira Server" (the self-hosted solution) is not supported.

Usage

Torii monitors Jira usage data daily.

1. We monitor all events for existing Jira issues listed in the Jira ticket activity log.
   Comments - Created/ edited/ deleted comments
2. History - Monitors issue's activities like attachments, dates, assign to, etc.
3. Work log - Created/ edited/ deleted work logs

If a Jira user completed at least one of the following actions on a given day:

• Created/ edited/ deleted comments
• Attached, assigned, changed an item
• Worked on the work log

The user will be considered an "Active user."

Once connected, Torii will show usage from the last 30 days

Note: Users who have set their email address to be hidden can not be synced from Jira.

License type

A Jira site usually contains multiple products:

• Jira Core, Jira Software, Jira Service Desk and more.
• Each user's product access will be shown as a license for the user.
• Note that "Jira Core" is included in other products.

Connect your Jira Cloud integration

When connecting the Jira integration, you will be asked to choose an Authentication Method. Torii supports two authentication methods:

• User Basic Auth – authentication using a user API token
• Service Account – authentication using an Atlassian service account

Follow the relevant steps below based on the authentication method you select.

User Basic Auth

Step 1: Log in to your Atlassian account. Make sure you have the following global permission:

1. Browse users and groups.

2. Administer Jira.

Step 2: Create an API token from your Atlassian account:

1. Go to https://id.atlassian.com/manage/api-tokens.
2. Click Create API token.
3. From the dialog that appears, enter "Torii" as the Label for your token and click Create.
4. Click Copy to clipboard and save the API token. Note that it isn't possible to view the token after closing the creation dialog; if necessary, create a new token.

Step 3: Get the Jira site URL. It should look like: https://your-domain.atlassian.net

Step 4: Go to the Torii Integrations page and click on the Jira Cloud tile in order to connect.

Step 5: Provide your Atlassian account email address, API Token, Jira site URL, Atlassian API Key, and Atlassian Organization ID.

Service Account Authentication

Service Account authentication allows Torii to connect to Jira without relying on a specific user. This method is recommended for long-term stability.

Create a Service Account in Atlassian

1. Log in to your Atlassian organization.
2. From the main menu, select Directory → Service accounts.
3. Click Create a service account.
4. Enter a name and click Next.
5. Select Jira Administration and assign the App admin role.
6. Optional: If you plan to use actions that add or remove users from groups, also select the site-admins group under Groups.
7. Click Create.

Create OAuth 2.0 credentials

1. In the created service account page, click Create credentials.
2. Select OAuth 2.0 and click Next.
3. Enter a name and click Next.
4. Select the following scopes:
   1. read:jira-user – Used to read user information.
   2. manage:jira-configuration – Allows performing user-related administrative actions.
   3. read:jira-work – Used to retrieve usage data and system information such as projects and issues.
   4. write:jira-work – Required for actions that perform operations on Jira issues.
   5. read:servicedesk-request – Used by actions to retrieve issue and request data.
5. Click Next.
6. Click Create.
7. Copy the generated Client ID and Client Secret and use them in the Torii connection form.

Retrieve your Cloud ID
Follow Atlassian’s official guide to retrieve your Jira Cloud ID: Retrieve my Atlassian site Cloud ID .

Connect the integration

• Go to the Torii Integrations page and click on the Jira Cloud tile in order to connect.

• Provide your Client ID, Client Secret, and Cloud ID.

• Optional: Provide Atlassian API Key, and Atlassian Organization ID to retrive user roles.

Actions

Torii supports taking actions in Jira, such as creating tickets and managing issues. Some actions require additional permissions in Jira, as outlined below.

Create Jira Ticket

To use the Create Jira Ticket action, the credentials used to connect the integration must belong to a user (or service account) that is also an administrator of the Jira project where the ticket is created.

Delete Jira Issue

Deleting Jira issues requires explicit permissions. How these permissions are granted depends on your Jira plan:

• Free plan
  Add the service account (or user used for the integration) directly to the relevant Jira project:

  • Open the project
  • Click Add people (top-right corner)
  • Add the service account with the Administrator role

  This role may grant the required permission to delete issues.

• Standard / Premium plans
  Jira administrators can explicitly grant delete permissions via permission schemes:

  1. Go to Settings → Work items → Permission schemes
  2. Select the relevant scheme and click Permissions
  3. Find Delete Issues and click Update
  4. Grant the permission to specific users, groups, or roles

  For more details, see Atlassian’s documentation: Grant or revoke permissions in a scheme .

Add / Remove Users from Groups

To be able to add or remove users from groups, make sure that the service account used to connect the integration is added to the site-admins group in Jira.

Q&A

Q: Will the 'Delete JIRA Cloud User' action in a workflow always delete a JIRA user?
A: No. If the user has opened a JIRA ticket in the past (and thus is a 'Reporter' in JIRA), Torii cannot delete them per JIRA's API limitations.

Get additional information in:

• Atlassian and Jira Cloud Integrations: A deeper look
• Open a Jira Ticket From Torii
• Delegate an Offboarding Task With Jira

Q: I am trying to connect the Jira integration, but getting an 'Invalid credentials' error. What should I do?

A: Please try the following steps:

1. Make sure the email who connected the integration is a global administrator
2. Give 'global permissions' to the connecting user's Jira group
3. Reassign admin Jira group for the connecting user