Skip to main content

Jira

Jira is a project management and issue tracking tool used for software development, task management, and agile project management.

This connector targets Jira Cloud. For the self-hosted product, use Jira Server instead.

Authentication Types​

Jira (Cloud) supports 3 authentication methods:

  • OAuth - Create your own Atlassian OAuth app with custom scopes. Every user connects with their Atlassian account.

    • Pros: Full control, per-user tracking, production-ready
    • Cons: ~2 min setup

  • Instant OAuth - Use Willow's pre-configured Jira app for the fastest setup.

    • Pros: Fastest setup, no configuration needed
    • Cons: Limited scopes, not recommended for production

  • API Key - Authenticate with one shared Atlassian token: a classic API token (email:api_token) from a dedicated account, or a scoped token from an Atlassian service account.

    • Pros: Easy setup
    • Cons: Single credential for all users

Configuration​

Before using the connector, you need to configure the Jira Organization Domain — the base URL Willow calls. You set it yourself, and the correct value depends on your authentication type. For API Key it depends specifically on which kind of token you paste:

Authentication typeCredential you enterJira Organization Domain to enterAuth header Willow sends
OAuth3LO access token (via consent)https://api.atlassian.com/ex/jira/{cloudId} (gateway)Bearer <token>
Instant OAuth3LO access token (via consent)https://api.atlassian.com/ex/jira/{cloudId} (gateway)Bearer <token>
API Key — classic tokenemail:api_tokenhttps://your-org.atlassian.net (bare site)Basic base64(email:token)
API Key — service accountscoped token, no emailhttps://api.atlassian.com/ex/jira/{cloudId} (gateway)Bearer <token>

Why the difference: Atlassian only accepts 3LO and scoped tokens through the api.atlassian.com gateway, while a classic API token (Basic auth) only works against the bare site. Willow picks the header automatically from the credential format — a value containing a colon (email:api_token) is sent as Basic, and a bare token (a scoped service-account token) is sent as Bearer — so you only need to set the Organization Domain to the matching value above.

Finding your Cloud ID​

On OAuth and Instant OAuth you can just enter your site, https://your-org.atlassian.net. When you save, Willow looks your Cloud ID up from the site itself and stores the gateway URL instead, then shows you what it saved. Nothing else to do.

To find the Cloud ID yourself — you need it for an API Key with a service-account token, which Willow does not rewrite:

  1. Sign in to your Jira site in a browser.
  2. Open https://your-org.atlassian.net/_edge/tenant_info (replace your-org with your Jira subdomain).
  3. The page returns JSON like {"cloudId":"e1acb0fb-318d-4fc3-ba56-db2b0ae14466", ...}. Copy the cloudId value.
  4. Substitute it into the gateway URL, for example https://api.atlassian.com/ex/jira/e1acb0fb-318d-4fc3-ba56-db2b0ae14466, and enter that as the Jira Organization Domain.

A classic-token API Key uses the bare site URL and needs no Cloud ID. If you move an integration from OAuth to a classic-token API Key, put the site URL back — the gateway URL left behind by the rewrite returns 401 for Basic auth.

Setting up OAuth​

  1. Go to https://developer.atlassian.com/console/myapps/

  2. Click Create → OAuth 2.0 integration

  3. Enter a name for your app and click Create

  4. In the left sidebar, go to Permissions

  5. Click Add next to Jira API and configure the scopes you need

    Minimal scopes (required for basic functionality):

    read:jira-user
    read:jira-work
    write:jira-work
    manage:jira-project
    read:project:jira

    Additional scopes for specific endpoints:

    read:issue:jira
    write:issue:jira
    read:attachment:jira

    Jira Software (Agile) scopes — for boards, sprints, and backlog:

    read:board-scope:jira-software
    write:board-scope:jira-software
    read:board-scope.admin:jira-software
    write:board-scope.admin:jira-software
    read:sprint:jira-software
    write:sprint:jira-software

  6. In the left sidebar, go to Authorization

  7. Click Add next to OAuth 2.0 (3LO)

  8. Set the Callback URL:

    • For SaaS deployments: https://{org}.mcp-s.com/{org}/api/auth/callback
    • For On-Premise deployments: {connectUrl}/{org}/api/auth/callback

  9. Click Save changes

  10. In the left sidebar, go to Settings

  11. Copy the Client ID and Secret

  12. In Willow, paste the Client ID and Client Secret

  13. Select the same scopes you configured in Atlassian, and also add offline_access

  14. Enter your Jira Organization Domain in Configuration.

    Since OAuth uses the Atlassian API gateway, the base URL should be:

    https://api.atlassian.com/ex/jira/{cloudId}

    For example: https://api.atlassian.com/ex/jira/e1acb0fb-318d-4fc3-ba56-db2b0ae14466

    To find your Cloud ID, open the following URL in your browser (replace your-org with your Jira subdomain):

    https://your-org.atlassian.net/_edge/tenant_info

    Copy the cloudId value from the JSON response.

  15. Click Save Changes

Setting up Instant OAuth​

  1. Click Connect to sign in with your Atlassian account.

  2. Find your Cloud ID by opening the following URL in your browser (replace your-org with your Jira subdomain):

    https://your-org.atlassian.net/_edge/tenant_info

    Copy the cloudId value from the response.

  3. In General Settings, enter your Jira organization domain using this format:

    https://api.atlassian.com/ex/jira/{cloudId}

    Replace {cloudId} with the value copied in the previous step.

  4. Click Save Changes.

Reading Jira Forms​

Jira issues (especially Jira Service Management requests like Cloud Account Request or onboarding forms) often carry native Jira forms. Some form questions are linked to Jira fields, but many are not — that data lives only inside the form and is not returned by the standard issue tools. Forms are served by a separate Atlassian API, so Willow exposes two dedicated tools:

  • Get Issue Forms — lists the forms attached to an issue and returns each form's formId, name and submitted state.
  • Get Issue Form Answers — takes a formId and returns the answers as a flattened list of { fieldKey, label, answer, choice } entries (multi-valued answers are joined into a comma-separated string).

Typical flow: call Get Issue Forms for an issue to get the formId, then call Get Issue Form Answers with that formId to read the submitted values.

What you need​

These tools call {orgDomain}/forms/..., so they reuse the same base URL and read:jira-work scope as the other Jira tools — no extra scope, consent, or configuration field. They work automatically as long as your Organization Domain is set to the Atlassian API gateway base, which already contains your Cloud ID:

https://api.atlassian.com/ex/jira/{cloudId}

This is the same value the OAuth and Instant OAuth setup steps above configure. To find your {cloudId}, open the following URL in your browser (replace your-org with your Jira subdomain) and copy the cloudId value from the JSON response:

https://your-org.atlassian.net/_edge/tenant_info
note

The forms tools require the gateway-style Organization Domain (https://api.atlassian.com/ex/jira/{cloudId}). Integrations authenticated with a classic API Key against a bare site domain (https://your-org.atlassian.net) can read issues but will not reach the Forms API, which is only served through the gateway. OAuth and service-account API keys already use the gateway, so they reach it.

Generating an API Key​

You can authenticate with either a classic token (technical user) or a scoped token (service account).

Classic token (technical user)​

  1. Sign in to the dedicated Atlassian account you want the integration to act as.

  2. Go to https://id.atlassian.com/manage-profile/security/api-tokens

  3. Click Create API token (a classic, unscoped token), give it a descriptive label, and click Create.

  4. Copy the token immediately.

  5. In Willow, enter the API key in the format your-email@example.com:your-api-token, and set the Jira Organization Domain to your bare site (https://your-org.atlassian.net).

Scoped token (service account)​

Atlassian service accounts are license-free identities that can only create scoped tokens, which Atlassian accepts as Bearer against the API gateway.

  1. As an org admin, create or open a service account and create an API token with the Jira scopes your enabled tools need.

  2. Copy the token immediately.

  3. In Willow, paste the token on its own (no email, no colon), and set the Jira Organization Domain to the gateway base (https://api.atlassian.com/ex/jira/{cloudId}). Willow detects the bare token and sends it as Bearer automatically.

On this page