> For the complete documentation index, see [llms.txt](https://docs.userlane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.userlane.com/administration/attributes/connect-an-attribute-source/jira.md).

# Jira

How to connect Jira as an attribute source, including the permissions needed, setup steps, and the values to enter in Userlane.

Connecting Jira gives Userlane access to user information from your Atlassian directory. Once connected, Jira appears as an attribute source and user data refreshes daily.

You do not need a Jira site administrator for this. One person can do the whole thing if they have both an Atlassian account and Userlane administrator access.

{% hint style="warning" %}
**Prerequisites.** You need an Atlassian account with access to the developer console[^1], and an account with the **Browse users and groups** global permission[^2] to authorize. On the Userlane side, you need an **Admin**, **Portfolio Owner**, or **Deployment Manager** role. Before starting, ask your Userlane contact for the callback address for Jira.
{% endhint %}

## What Userlane reads from Jira

Userlane checks Jira against its standard set of attributes. See [Connect an attribute source](/administration/attributes/connect-an-attribute-source.md) for the full list and how matching works.

What that means for Jira specifically:

* Custom fields and anything outside the standard set are ignored at the point of collection and never stored.
* Attributes in the standard set that Jira does not carry stay blank.
* People who have never opened Userlane are skipped. A Jira user without a matching Userlane account receives nothing.

Userlane never writes to Jira or changes anything in it.

{% hint style="info" %}
**Set expectations on Jira specifically.** Jira holds much less about a person than a human resources (HR) system or identity provider does. It is a project tool, not a people system, so most of the attributes Userlane looks for are not there. Treat Jira as a supplementary source rather than a primary one, and connect an HR system or identity provider alongside it if you need job title, department, or reporting lines.
{% endhint %}

## Who you need

**To create the app:** anyone with an Atlassian account who can use the developer console.

**To authorize the connection:** an account with the **Browse users and groups** global permission.

That permission sits one level below **Administer Jira**. Administrators have it automatically, but it can also be granted to a group, so you do not have to involve a Jira administrator if you would rather not.

**Why this permission matters, and how it fails.** Without **Browse users and groups**, Jira does not return an error. It returns an empty list. The connection will look successful and deliver nothing.

**Email visibility affects matching.** Userlane identifies people by email address, and Atlassian applies each person's account privacy settings to what its application programming interface (API) returns. People whose email is not visible cannot be matched and will not receive attributes. Your Atlassian administrator can tell you how your organization's privacy settings are configured.

## Create the app

{% stepper %}
{% step %}

#### Open the Atlassian developer console

Sign in to the Atlassian developer console.
{% endstep %}

{% step %}

#### Create an OAuth 2.0 integration

Create a new OAuth 2.0 integration and give it a name you will recognize later, for example "Userlane attribute sync."
{% endstep %}

{% step %}

#### Add permissions

Under **Permissions**, add the Jira API and the scopes needed to read user records.
{% endstep %}

{% step %}

#### Add the callback address

Under **Authorization**, add the callback address your Userlane contact gave you.
{% endstep %}

{% step %}

#### Copy the credentials from Settings

Open **Settings** and copy the **Client ID** and **Secret**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**The values are on Settings, not Overview.** The console opens on the **Overview** page, which shows an **App ID**. That is a different identifier Atlassian uses internally and it is not part of the connection. The two values Userlane needs are on the **Settings** page.
{% endhint %}

{% hint style="warning" %}
**Do not rotate the secret afterwards.** Generating a new secret from **Settings** breaks the existing connection and forces you to set it up again.
{% endhint %}

## Find the values Userlane asks for

| Userlane asks for | In Atlassian this is                          |
| ----------------- | --------------------------------------------- |
| **Client ID**     | **Client ID**, on the app's **Settings** page |
| **Client secret** | **Secret**, on the same page                  |

Have the person who created the app enter the values into Userlane themselves if possible. If that is not practical, use whatever tool your organization uses for sharing credentials rather than email or chat.

## Connect in Userlane

{% stepper %}
{% step %}

#### Open Attribute sources

In the portal, go to **Attribute sources** under company settings.
{% endstep %}

{% step %}

#### Select Jira and enter the values

Select **Jira**, then enter the Client ID and Secret.
{% endstep %}

{% step %}

#### Authorize with the right account

Complete the Atlassian sign-in when prompted, **using an account that holds Browse users and groups**.
{% endstep %}
{% endstepper %}

Once connected, Jira appears under connected sources. The first sync usually finishes within about fifteen minutes, and Userlane then refreshes overnight once a day. For troubleshooting, see [Connect an attribute source](/administration/attributes/connect-an-attribute-source.md).

## If you have more than one Jira site

Authorization applies to the single site you select when you approve the connection. If your organization runs several Jira sites and you want people from all of them, repeat the process for each.

## Worth knowing

Jira only holds records for people who use Jira, which makes it the narrowest of the sources Userlane can connect. If parts of your organization do not use it, those people will not receive attributes from this source.

A connection that sits unused for around three months loses its authorization, because Atlassian expires it. If a Jira connection has been switched off for a while, expect to reconnect it rather than re-enabling it. Userlane does not notify you when this happens.

## Relevant articles

{% content-ref url="/pages/5RV9H7dUyIbkTHBrF8Av" %}
[Connect an attribute source](/administration/attributes/connect-an-attribute-source.md)
{% endcontent-ref %}

{% content-ref url="/pages/heUmxS6HxlGKqCQSjqbs" %}
[Attribute sources](/administration/attributes/attribute-sources.md)
{% endcontent-ref %}

{% content-ref url="/pages/dOsfp2lveEGwAS8a7Pkt" %}
[ServiceNow](/administration/attributes/connect-an-attribute-source/servicenow.md)
{% endcontent-ref %}

{% content-ref url="/pages/b1SMRSBtvkd1sZZNi9U4" %}
[Salesforce](/administration/attributes/connect-an-attribute-source/salesforce.md)
{% endcontent-ref %}

## FAQ

<details>

<summary>Do I need a Jira administrator to connect?</summary>

No. Anyone with an Atlassian account can create the app in the developer console. The authorizing account needs **Browse users and groups**, which administrators have automatically but which can also be granted to a group.

</details>

<details>

<summary>Why are some people missing after connecting?</summary>

Two likely causes. Either those people have a different email in Atlassian than in Userlane, or their Atlassian privacy settings hide their email from the API. Check with your Atlassian administrator.

</details>

<details>

<summary>Does Userlane write anything back to Jira?</summary>

No. The connection is read-only. Userlane never creates, updates, or deletes anything in Jira.

</details>

[^1]: The Atlassian developer console is where you register integrations that connect external applications to your Atlassian products.

[^2]: A global permission in Jira applies across the whole Jira site rather than to a single project.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.userlane.com/administration/attributes/connect-an-attribute-source/jira.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.