> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/configuration-guide/integrations/jira/authentication.md).

# Authentication

Set up authentication between Pharos and Jira.

Pharos supports two authentication methods for connecting to Jira. Choose based on your Jira hosting model:

| Method                | Use When                                    |
| --------------------- | ------------------------------------------- |
| **Connect via OAuth** | Jira Cloud (`.atlassian.net`) — recommended |
| **Connect via API**   | Jira Server / Data Center (self-hosted)     |

{% hint style="info" %}
For what the Jira integration sends outside your org and the access it requires, see [Security & Data Access](https://docs.pharos.ai/configuration-guide/security.md).
{% endhint %}

***

## Accessing Jira Authentication Settings

1. Open the **Pharos** app
2. Navigate to **Pharos Admin**
3. Select **Integrations** from the left-hand menu
4. Click **Jira**
5. Select the **Authentication** sub-section

***

## Option 1: Connect via OAuth (Jira Cloud)

OAuth is the recommended method for Jira Cloud. Pharos handles the token exchange — you just log in and approve access.

1. Select **Connect via OAuth**
2. Click **Login to Jira**

![Jira Authentication Settings — Connect via OAuth selected, showing OAuth Token field with Login to Jira and Reset buttons](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-e7f1956397ac7053af72e1b28fc5a8bb52c60b56%2Fjira-auth-oauth.png?alt=media)

3. You'll be redirected to Atlassian's authorization page
4. Select the Jira site to connect (e.g., `yourcompany.atlassian.net`)
5. Review the permissions Pharos requests and click **Accept**

![Atlassian OAuth consent — Pharos requests View (jira-user, jira-work) and Update (jira-work) permissions](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-7b1597afad1d513481bba27a56a666f1af23f880%2Fjira-oauth-consent.png?alt=media)

6. After accepting, you'll be redirected back to Pharos
7. The **OAuth Token** field will display a masked token, confirming the connection

### OAuth Permissions

Pharos requests the following Jira scopes:

| Scope               | Access                                                                          |
| ------------------- | ------------------------------------------------------------------------------- |
| **jira-user**       | View — read user and project information                                        |
| **jira-work**       | View — read issues, comments, worklogs                                          |
| **jira-work**       | Update — create and update issues, add comments                                 |
| **offline\_access** | Maintain access — refresh the connection without requiring you to sign in again |

These scopes allow Pharos to create tickets, update ticket status, link related issues, and keep the connection alive via refresh tokens.

{% hint style="info" %}
**Who authenticates matters.** The user who completes the OAuth flow determines the permissions available to Pharos. Use an account with access to all target Jira projects. Consider a dedicated service account so the integration isn't tied to a personal account.
{% endhint %}

### Resetting the OAuth Connection

Click **Reset** to clear the stored OAuth token. You'll need to click **Login to Jira** again to re-establish the connection. Use this if:

* The authenticating user's Jira account was deactivated
* You need to switch to a different Jira user
* The token has expired or become invalid

***

## Option 2: Connect via API (Jira Server / Data Center)

Use this method for self-hosted Jira instances where OAuth isn't available or your organization requires API token authentication.

1. Select **Connect via API**
2. Fill in the following fields:

![Jira Authentication Settings — Connect via API selected, showing Base URL, Email or Username, and API Token fields](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-f6a6a358025253f53e6ed88a875dcb092feef823%2Fjira-auth-api.png?alt=media)

| Field                 | Description                                                                                                                                                                      | Example                        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| **Base URL**          | Your Jira instance URL. Open any Jira issue and note the domain from the address bar.                                                                                            | `https://jira.yourcompany.com` |
| **Email or Username** | The Jira user account for the integration                                                                                                                                        | `pharos-integration`           |
| **API Token**         | API token for authentication. See [Atlassian Support](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) for how to create one. | (masked)                       |

3. Click **Save**

{% hint style="warning" %}
The API token grants access to Jira on behalf of the specified user. Store it securely. If compromised, revoke it in your Jira instance and create a new one.
{% endhint %}

### Resetting the API Connection

Click **Reset** to clear all stored credentials (Base URL, username, and token). You'll need to re-enter them to reconnect.

***

## Verifying the Connection

After either authentication method:

* The token field should display a masked value
* Test by navigating to **Ticketing → Actions** and creating a test action — the Jira project dropdown should populate with your projects
* If projects don't appear, the authenticating user may lack access to those projects

***

## Sandbox and Post-Refresh Considerations

When you refresh a sandbox from production, Jira credentials are copied but may point to a production instance. After a sandbox refresh:

1. Run the [Quick Start](https://docs.pharos.ai/configuration-guide/quick-start.md) wizard with the **Sandbox Refresh** option
2. Review the authentication settings — you may want to connect to a different Jira project or use sandbox-specific credentials
3. Update [Defaults](https://docs.pharos.ai/configuration-guide/integrations/jira/defaults.md) to use sandbox-appropriate settings

***

## Troubleshooting

| Issue                                     | Cause                                   | Resolution                                                                                       |
| ----------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------ |
| "Unauthorized" or 401                     | Invalid token or credentials            | **OAuth:** click Reset, then Login to Jira again. **API:** verify Base URL, username, and token. |
| "Forbidden" or 403                        | User lacks project permissions          | Grant "Create issues" and "Edit issues" in the target Jira project                               |
| Projects not appearing in action dropdown | Authenticating user doesn't have access | Verify the user has access to the target projects in Jira                                        |
| OAuth consent fails                       | Jira admin restrictions                 | Your Jira admin may need to approve the Pharos app in Atlassian admin settings                   |

{% hint style="success" %}
**Next Step:** Configure [Defaults](https://docs.pharos.ai/configuration-guide/integrations/jira/defaults.md) to set up synchronization controls and ticket behavior.
{% endhint %}
