The following guide explains:

  • How to set up a Jira app & configure it
  • Connect Jira with Apideck
  • Subscribe to Jira webhooks

Create a Jira app & connect via Apideck

Sign up for Jira

Go to the Atlassian website and Sign up - Try Atlassian Cloud | Atlassian to get a free account (no credit card required.)

Fill out the sign-up form with your details and click "Agree". You should receive a verification email.

Log in to Jira

After you have signed up with Jira, you can log in to Jira to create an "Application".

You can do this by visiting the Atlassian Developer Center (https://developer.atlassian.com/) and clicking on "Log in" in the top right corner. Enter your login credentials and click on the "Continue" button.

Register a Jira OAuth app

After you are logged in, go to the "Developer Console" page from the menu under your avatar in the right top part of the screen.

You can create a new OAuth app by clicking on the "Create" button within the "My Apps" section.

Select the "OAuth 2.0 integration" for creating a new application

This will take you to a form where you can enter the required information about your app:

  • App Name: Enter a meaningful name (for example, 'Apideck integration'), since when your users link their Jira account, they will see the “App Name” is requesting to integrate.

Press "Create" to go ahead and create the app.

Configure your Jira OAuth app

After creating your app, you'll need to configure it by setting up various settings and permissions.

This includes setting up OAuth 2.0 authentication, and configuring your app's terms & conditions, branding and icons.

Configure OAuth permissions

The next step is to configure the OAuth 2.0 permissions.

From the side menu, navigate to "Permissions".

Jira API permissions

From the overview of Permissions, click on the "Add" button for Jira API to configure the permissions.

For the Issue tracking, we recommend setting the following Jira API permissions:

  • View Jira issue data -

    read:jira-work
    Read Jira project and issue data, search for issues, and objects associated with issues like attachments and worklogs.

  • Manage project settings - manage:jira-project Create and edit project settings and create new project-level objects (e.g. versions and components).

  • Manage Jira global settings -

    manage:jira-configuration
    Take Jira administration actions (e.g. create projects and custom fields, view workflows, manage issue link types).

  • View user profiles -

    read:jira-user
    View user information in Jira that the user has access to, including usernames, email addresses, and avatars.

  • Create and manage issues -

    write:jira-work
    Create and edit issues in Jira, post comments as the user, create worklogs, and delete issues.

  • Manage Jira webhooks -

    manage:jira-webhook

    Register and manage Jira webhooks.

  • Manage development -

    manage:jira-data-provider
    Manage development and release information for third parties in Jira.

Configure authorization

To manage the authorization, go to "Authorization" in the side menu.

Click on the "Add" button, to set the callback URI for the OAuth app.

Callback URL: The URL where the user will be redirected after granting your app access to their Jira account. This should be

https://unify.apideck.com/vault/callback
.

Authentication details & app settings

To grab the authentication details, go to "Settings" in the side menu. After you have defined the authorisation, the Client ID & Secret will be automatically generated.

Click on the "Generate new secret" button to generate a new Client Secret.

💡 TIP: Copy the "Client Id" and the "Client secret". You will need them in the next step.

The app setting allows you to configure the name, avatar and description + the Authentication details.

Vault Connection Setup

Now that you have your Jira App credentials, you can enable the integration to connect to your Jira instance in a secure manner. Once this is done you can start testing it by using Jira APIs and sandbox environment. You can also use Jira sandbox environment to test your app's integration with Jira without affecting real data.

Goto the Apideck > Configuration > Issue Tracking > Jira

Enter the OAuth client ID & Secret from Jira and review if the scopes granted in Jira match with the scopes you are requesting in Apideck.

Press "Save settings" to save your credentials.

You can test the connection by clicking "Test Vault", which will check if the connection is working.

🚀Now you are ready and clients can authorize the connection to their Jira account in a secure way.

Do your first Jira API call via the Issue Tracking API

curl \
  --request GET \
  --url 'https://unify.apideck.com/issue-tracking/collections' \
  --header 'Authorization: Bearer {APIDECK_API_KEY}' \
  --header 'x-apideck-app-id: {APIDECK_APP_ID}' \
  --header 'x-apideck-consumer-id: test-consumer' \
  --header 'x-apideck-service-id: jira'

Jira Webhook Registration

Webhook subscription in Jira

Apideck will auto-register for webhook events from Jira integrations.

💡 IMPORTANT: To allow the auto-registration of Jira webhook events, but sure request the "Manage Jira webhooks -

manage:jira-webhook
" permission. See Configure OAuth permissions for how to properly configure the scopes.

Subscribe to Unify events

After you have completed the above steps, you can subscribe to your application to Unify Events.

The following guide will explain all the steps to subscribe to Unify webhooks events: How to subscribe to webhook events