> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira Cloud from self-hosted Overcut

> Connect Atlassian-hosted Jira Cloud to a self-hosted Overcut deployment using your own OAuth app.

Use this path when you run **Overcut on your own infrastructure** and your Jira is
**Atlassian-hosted Jira Cloud** (`https://<your-company>.atlassian.net`). Instead
of the managed Forge app, you connect directly with your **own** Atlassian OAuth
2.0 app. Each deployment brings its own credentials; there is no shared Overcut
Cloud client.

<Note>
  Not your setup? See [Which setup do I need?](/docs/integrations/jira#which-setup-do-i-need).
  On **Overcut Cloud**, use the [Forge app](/docs/integrations/jira/cloud) instead.
  For on-prem Jira, see [Jira Server / Data Center](/docs/integrations/jira/data-center).
</Note>

## Prerequisites

* An **Atlassian Jira Cloud** workspace (`https://<your-company>.atlassian.net`)
* Admin access to the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/)
* A self-hosted Overcut deployment you operate (see [Deployment configuration](#deployment-configuration))

<Warning>
  The Atlassian account you authorize with **owns every issue, comment, and
  transition** Overcut performs. Authorize while signed in as a dedicated service
  account (for example `overcut-bot`), not your personal admin account. An
  incognito window is the safe way to avoid consenting as yourself. The service
  account must be a licensed Jira user with real access to the target projects.
</Warning>

## Choose an authorization type

The connect modal has an **Authorization type** toggle:

* **User authorization (3LO)** - the default, covered by the steps below. A
  browser **Authorize** step runs once, and Overcut acts on behalf of the
  consenting Atlassian service account. Overcut obtains a refresh token so the
  connection survives long-running sessions.
* **Service account (2LO)** - no browser consent. Recommended when your org
  offers service-account credentials or when an org policy blocks interactive
  OAuth app authorization. See [Use a service account (2LO)](#use-a-service-account-2lo).

The effective permission is always the app's scopes **intersected with** the
connected account's actual Jira permissions.

## Connect with user authorization (3LO)

<Steps>
  <Step title="Create an OAuth 2.0 app in the Atlassian Developer Console">
    Go to the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/),
    sign in, and select **Create -> OAuth 2.0 integration**. Name it (for example
    `Overcut`) and accept the terms.

    Creating the app grants no access by itself, and it does not matter which
    person creates it. It yields the **Client ID + Secret** that identify the app.
  </Step>

  <Step title="Add the Jira permissions">
    In the app's **Permissions** tab, add the **Jira API** and configure **Classic
    scopes**. Enable exactly these three:

    * **`read:jira-work`** - view issues, projects, fields, and comments
    * **`write:jira-work`** - create, update, transition, and link issues and comments
    * **`read:jira-user`** - resolve the service-account identity (`/myself`) and @mentions

    **Scopes Used** should read **3**. Do not add the separate **User identity
    API** or Confluence / Compass scopes.

    You do not add `offline_access` here - it is a standard OAuth scope, not a Jira
    API scope. Overcut requests it automatically during authorization to obtain a
    refresh token.
  </Step>

  <Step title="Set the callback URL">
    In the **Authorization** tab, add **OAuth 2.0 (3LO)** and set the **Callback URL**
    to your deployment's Overcut callback, exactly:

    ```
    https://<your-overcut-domain>/jira-cloud-auth-app/callback
    ```

    This must match the `JIRA_CLOUD_REDIRECT_URI` server setting character for
    character (scheme, host, path, no trailing slash), and must use **https**
    (except `http://localhost:<port>` for local development).
  </Step>

  <Step title="Copy the credentials">
    In the app's **Settings** tab, copy the **Client ID** and **Secret**.
  </Step>

  <Step title="Connect in Overcut">
    In Overcut, open the git providers list and click the **Jira Cloud
    (self-hosted connect)** tile. Leave the authorization type as **User
    authorization (3LO)**. Enter your **Site URL**
    (`https://<your-company>.atlassian.net`) and the **Client ID** and **Secret**
    from the previous step.

    Make sure your browser session is signed into Atlassian **as the service
    account**, then click **Authorize**. Overcut resolves your `cloudId`
    automatically from the site you entered and stores the connection.
  </Step>

  <Step title="Register the webhook in Jira">
    Webhooks are configured in Jira, separately from the OAuth app. Open the
    connected org's **settings** page in Overcut (**View settings** on the provider
    page) to find the webhook **URL** (shaped like
    `https://<dispatcher>/webhooks/jira/cloud/<orgId>?secret=<token>`).

    In Jira, go to **Settings (cog) -> System -> WebHooks -> Create a WebHook**, paste
    the full URL (use **Copy full URL** in Overcut so the real secret is embedded),
    and under **Events** enable issue **created / updated / deleted** and comment
    **created / updated / deleted**. Leave the JQL filter empty to receive all
    projects, or scope it.
  </Step>
</Steps>

## Use a service account (2LO)

Use this when you prefer a headless service-account credential over a browser
consent, or when an org policy blocks interactive OAuth app authorization. 2LO is
available for Jira Cloud only.

<Steps>
  <Step title="Create a service account">
    In **admin.atlassian.com**, create a service account (for example
    `overcut-bot`). This is the identity every Overcut action will be attributed
    to.
  </Step>

  <Step title="Grant the service account access to Jira (required)">
    On the service account, click **Grant access** and select your **Jira** app /
    site. The account must have **product access to the Jira site** and be added
    to the target project(s) with **Browse Projects** plus the write permissions.

    Do this **before** creating the credential. Without it, the credential
    authenticates but every Jira API call returns **403** and Overcut shows "no
    projects available".
  </Step>

  <Step title="Create an OAuth 2.0 credential">
    On the service account, click **Create credentials**. On the **Choose
    authentication type** screen, select **OAuth 2.0** (Recommended) and click
    **Next**. Give the credential a name, then select exactly these three Jira
    scopes:

    * **`read:jira-work`** - view issues, projects, fields, and comments
    * **`write:jira-work`** - create, update, transition, and link issues and comments
    * **`read:jira-user`** - resolve the service-account identity and @mentions

    There is **no callback URL** for this credential. Finish, then copy the
    generated **Client ID** and **Secret**. See Atlassian's
    [Create an OAuth 2.0 credential for service accounts](https://support.atlassian.com/user-management/docs/create-oauth-2-0-credential-for-service-accounts/)
    for details.
  </Step>

  <Step title="Connect in Overcut">
    Open the **Jira Cloud (self-hosted connect)** tile and switch the
    **Authorization type** to **Service account (2LO)**. Enter the **Site URL**
    plus the credential's **Client ID** and **Secret**, and click **Connect**.

    There is **no callback URL and no browser Authorize step**. The token *is* the
    service account; Overcut resolves the `cloudId` from the Site URL and renews
    by re-requesting (2LO has no refresh token).
  </Step>

  <Step title="Register the webhook in Jira">
    Webhook setup is identical to the 3LO path - see
    [Register the webhook in Jira](#connect-with-user-authorization-3lo) above.
  </Step>
</Steps>

## Deployment configuration

These settings are configured once by whoever operates the self-hosted Overcut
deployment.

| Setting                          | Value                                                        | Notes                                                             |
| -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------- |
| `INTEGRATION_JIRA_CLOUD_ENABLED` | `true`                                                       | Defaults to enabled if unset. Set `false` to hide the tile.       |
| `JIRA_CLOUD_REDIRECT_URI`        | `https://<your-overcut-domain>/jira-cloud-auth-app/callback` | Must equal the developer-console Callback URL exactly (3LO only). |
| `DISPATCHER_BASE_URL`            | `https://<dispatcher-or-app>/hooks`                          | External URL used to build the webhook URL shown in Overcut.      |

## Troubleshooting

* **`redirect_uri` mismatch at Authorize**: the developer-console Callback URL and `JIRA_CLOUD_REDIRECT_URI` are not byte-identical (often a trailing slash or `http` vs `https`).
* **"No accessible site matches ..." after consent**: the account you authorized with does not have access to the Site URL you entered, or the Site URL is wrong. The error lists the sites the consent actually granted.
* **Actions attributed to the wrong person, or bot loops**: you consented as your personal account instead of the service account. Re-authorize in an incognito window signed in as the bot account.
* **Authorize blocked by an org policy**: some organizations restrict external OAuth app authorization (**Admin -> Security -> external app access**). A site admin must allow the app, or use [2LO](#use-a-service-account-2lo) instead.
* **2LO connects but every call returns 403 / no projects**: the service account has the OAuth credential but no product access. Grant it Jira product access and **Browse Projects** on the target projects in admin.atlassian.com.
* **Webhook events never fire**: confirm the webhook URL still includes `?secret=...`, the issue and comment events are enabled on the Jira webhook, and `DISPATCHER_BASE_URL` is set to the external URL.

For concepts shared across all Jira setups (issue operations, status-name rules,
ticket links), see the [Jira overview](/docs/integrations/jira).