Jira uses HTTP basic authentication with a username and API Token.

## Creating a user

All API Tokens are associated with a user and mirror the policies that are assigned to the user. It is common practice to create a group and assign permissions to the group, and finally make the user part of the group. For more details, see [Atlassian's documentation on user management](https://confluence.atlassian.com/adminjiraserver/user-management-938847014.html).

### 1. Log in to Jira as an Admin

Once logged in, navigate to gear icon (top right) -> User Management.

### 2. Click on groups in left panel

Once in the groups screen, create a group.

### 3. Assign correct permissions to group

In the bottom part (Group product access) Select the product "User" (Can access the product, with no product admin permissions). We are implementing a simple setup. It is possible to do project based setup but that is for advanced users. Hit Save.

In addition, in certain product configurations, the user may need read and write access to specific projects of interest. Please refer to Jira Documentation for details.

### 4. Click on users in left panel

Create a user with a password. Assign the user to the group you created above, using the lower part of this panel. Hit Save.

Please note that user creation is not mandatory. However it is strongly recommended that you create a service user rather than tie the API token to a specific user who can leave your organization and thus break your integration.

### 5. Login as the service user

Once logged in, navigate to gear icon (top right) -> Personal Settings (atlassian account settings).

### 6. Create an API Token for the Service User

In the top menu, go to "security". Click on "Create and Manage API Tokens", In the panel that opens up you can create API Tokens. Please note that the API Token will only be available at creation time. If its lost, you will have to revoke it and recreate a new token. It is best practice to rotate tokens every 90 days at least. More details are [in Atlassian's documentation](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).

## Configuring Permissions for JIRA Service Management

After completing the steps above, you will also need to navigate to the *Project settings* page for your Jira Service Management project, then find Access -> People and access. Select the "Add people" button, and add the service account to the project with the "Service Desk Team" role.

## Configure the Integration

Create your integration by supplying the following values.

**URL**
The root URL of your Jira instance. This may be in the format `https://<tenant>.atlassian.net/`.

**Username**
The username of the user account created in step 4.

**Password**
The API Token created in step 6.

## Custom Fields

To configure custom fields for this integration, see the [Jira Ticketing Provider Custom Fields Configuration Guide](/guides/provider-configuration/jira-custom-fields-setup).

## Ticket Hierarchy and the `parent` Field

Jira supports a native parent-child relationship between issues. Synqly exposes this through the `parent` field on the `Ticket` type.

### Supported operations

| Operation | Behaviour |
|  --- | --- |
| `CreateTicket` | Set `parent` in the request body to create the ticket as a child of an existing ticket. |
| `PatchTicket` | Use JSON Patch `add` or `replace` on `/parent` to reparent a ticket, or `remove` to clear the parent. |
| `GetTicket` | The `parent` field is populated with the parent ticket's key whenever a parent is set in Jira. |


### Referencing a parent

Pass either the ticket **key** (e.g. `"PROJ-42"`) or the numeric **internal ID** (e.g. `"10001"`) in the `parent` field. Synqly automatically selects the correct Jira API format based on the value.

### Issue hierarchy

Jira Cloud enforces a fixed issue hierarchy. Common supported relationships are:

- **Epic → Story / Task / Bug** (and other standard non-Epic issue types)
- **Task / Story → Sub-task**


Attempting to assign a parent that violates Jira's configured hierarchy (for example, setting an Epic as a child of another Epic) will return a `400` error from Jira.

> **Note:** Synqly maps only the native Jira `parent` field. The deprecated *Epic Link* and *Parent Link* custom fields are not used.


## Ticket Hierarchy in Jira Service Management

The `parent` field works the same way in Jira Service Management as in standard Jira (see [Ticket Hierarchy and the `parent` Field](#ticket-hierarchy-and-the-parent-field) above), with one important difference.

**Many JSM projects do not include the Epic issue type.** In those projects the supported parent-child relationship is:

- **Task → Sub-task**


When creating or patching a Sub-task, set `parent` to the key of an existing Task (or whichever issue type acts as the top-level item in your JSM project). Attempting to use an Epic as a parent in a project that does not support Epics will return a `400` error from Jira.