Skip to main content
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.
Not your setup? See Which setup do I need?. On Overcut Cloud, use the Forge app instead. For on-prem Jira, see Jira Server / Data Center.

​
Prerequisites

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.

​
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).
The effective permission is always the app’s scopes intersected with the connected account’s actual Jira permissions.

​
Connect with user authorization (3LO)

1

Create an OAuth 2.0 app in the Atlassian Developer Console

Go to the Atlassian Developer Console, 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.
2

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.
3

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).
4

Copy the credentials

In the app’s Settings tab, copy the Client ID and Secret.
5

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.
6

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.

​
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.
1

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.
2

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”.
3

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 for details.
4

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).
5

Register the webhook in Jira

Webhook setup is identical to the 3LO path - see Register the webhook in Jira above.

​
Deployment configuration

These settings are configured once by whoever operates the self-hosted Overcut deployment.
SettingValueNotes
INTEGRATION_JIRA_CLOUD_ENABLEDtrueDefaults to enabled if unset. Set false to hide the tile.
JIRA_CLOUD_REDIRECT_URIhttps://<your-overcut-domain>/jira-cloud-auth-app/callbackMust equal the developer-console Callback URL exactly (3LO only).
DISPATCHER_BASE_URLhttps://<dispatcher-or-app>/hooksExternal 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 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.