# Connect Jira

Canonical URL: https://docs.fuse.init.inc/integrations/jira/setup

Configure a Jira Cloud OAuth 2.0 (3LO) app and create a verified Init connection.



## Before you start [#before-you-start]

**Engine operator** registers one Atlassian OAuth 2.0 (3LO) app for Jira. **Connection admin/user** consents for their Jira Cloud site during Connect.

Jira and Confluence are **separate** Init providers and must use separate Atlassian app credentials (`JIRA_*` versus `CONFLUENCE_*`). Do not reuse one Atlassian app’s client secret across both unless you intentionally dual-configure the same client for both products and accept the shared blast radius.

You need:

* An Atlassian developer account to create OAuth 2.0 (3LO) apps.
* A Jira Cloud site admin or user who can consent to the requested scopes.
* The engine public base URL for the callback URL.

## Configure the provider [#configure-the-provider]

### One-time platform Jira OAuth app (**Engine operator**) [#one-time-platform-jira-oauth-app-engine-operator]

1. In the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/), create an OAuth 2.0 (3LO) app.

2. Add the callback URL:

   `{FUSE_PUBLIC_URL}/v1/oauth/jira/callback`

3. Under permissions, enable only the Jira Cloud scopes required by the Init actions you expose. Do not enable Confluence scopes on the Jira app “just in case.”

4. Copy the client ID and client secret into the Fuse environment as `JIRA_CLIENT_ID` and `JIRA_CLIENT_SECRET`. Never commit these values.

### Per-site authorization (**Connection admin/user**) [#per-site-authorization-connection-adminuser]

Each customer authorizes access to their Atlassian cloud site through Init Connect. No Jira API tokens are pasted into Connect for this provider.

## Connect to Init [#connect-to-init]

1. **Connection admin/user** starts a Jira Connect session.
2. Sign in to Atlassian and approve the Jira scopes for the correct cloud site.
3. Init exchanges the authorization code and stores the connection. No customer credential fields are submitted.

After Init enables additional Jira actions that need new scopes, reconnect so Atlassian re-consents to the expanded grant.

## Permissions [#permissions]

Classic and granular Jira scopes are listed on the generated scope matrix. Prefer granular scopes when your Atlassian app distribution supports them for the actions you ship.

Site admins may restrict which apps users can authorize. Consent is per Atlassian account and selected cloud resource; switching Jira sites requires a new Connect flow.

## Verify the connection [#verify-the-connection]

1. Confirm Connect completes and Init shows an active Jira connection for the expected cloud site.
2. Run a safe read such as listing projects the authorizing user can view.
3. Success looks like Jira returning project or issue metadata without `401`/`403` authorization failures.

## Rotate or revoke access [#rotate-or-revoke-access]

* **Rotate platform secrets (Engine operator):** rotate the Atlassian client secret, update `JIRA_CLIENT_SECRET`, then retire the old secret.
* **Revoke customer access (Connection admin/user):** remove the app from Atlassian account connected apps, or delete the Init connection.
* Scope expansion requires reconnect/reauthorize before new actions succeed.

## Troubleshooting [#troubleshooting]

| Symptom                                         | What to check                                                              |
| ----------------------------------------------- | -------------------------------------------------------------------------- |
| Callback mismatch                               | Callback must be `{FUSE_PUBLIC_URL}/v1/oauth/jira/callback`.               |
| Consent missing Jira scopes                     | Platform app permissions must include the scopes for your enabled actions. |
| Connected wrong site                            | Re-run Connect and select the intended Atlassian site.                     |
| Confluence actions failing on a Jira connection | Use the separate Confluence provider and `CONFLUENCE_*` app configuration. |
| Fuse cannot start OAuth                         | Confirm `JIRA_CLIENT_ID` and `JIRA_CLIENT_SECRET` on Fuse.                 |