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 - Use your Atlassian email and API token for authentication.

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

Configuration​

Before using the connector, you need to configure:

  • Jira Organization Domain - Your Jira instance domain (e.g., yourcompany.atlassian.net)

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

Generating an API Key​

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

  2. Click Create API token

  3. Give your token a descriptive label

  4. Click Create

  5. Copy the token immediately

  6. In Willow, enter the API key in the format: your-email@example.com:your-api-token

On this page