Guides

Jira

How to add the Jira integration.

Prerequisites

To add a new integration click on the + Add Integration button.

Adding the integration

When adding a Jira integration, fill in the following fields:

  • Provider - Select Jira from the dropdown.

  • Integration Name - A friendly name to identify this connection within Waydev.

  • Credentials - Jira supports three authentication methods:

    • Username and Password - Authenticate using your Jira account credentials, which requires:
      • Credentials set name - A label to identify this set of credentials.
      • Username - The username associated with your Jira account.
      • Password - The password for your Jira account.
      • Base URL - The base URL of your Jira instance (e.g. https://yourcompany.atlassian.net).
        Click Test credentials to verify that Waydev can successfully connect using the provided details.
    • Token - Authenticate using a personal access token instead, which requires:
      • Credentials set name - A label to identify this set of credentials.
      • Personal Access Token - The personal access token generated from your Jira account.
      • Email - The email address associated with your Jira account.
      • Base URL - The base URL of your Jira instance (e.g. https://yourcompany.atlassian.net).
        Click Test credentials to verify that Waydev can successfully connect using the provided details.
    • Jira Service Account
      • Credentials set name - A name to identify this set of credentials.
      • Client ID - The Client ID generated when creating the OAuth 2.0 credentials in the Atlassian Admin Console.
      • Client Secret - The Client Secret generated when creating the OAuth 2.0 credentials. This is only shown once at creation time, so it must be saved and entered here from where it was stored.
      • Base URL - Your Jira instance base URL (e.g. https://your-company.atlassian.net).

You can add multiple credential sets using the + Add credentials button. Click Cancel to discard the integration setup and return to the Integrations list.

Setting up a Jira Service Account for Waydev

This guide details how to create and configure an Atlassian Service Account with the proper permissions and OAuth 2.0 scopes to authenticate and sync Jira data with Waydev.

What is an Atlassian Service Account?

Atlassian Service Accounts are non-human accounts designed for machine-to-machine integrations (such as Waydev). They do not consume standard user licenses, and their permissions are strictly scoped to the tasks they need to perform, which improves security and auditability.

Step 1: Create the service account

To create a service account, you must be an Organization Administrator in Atlassian.

  1. Go to the Atlassian Administration Console.
  2. Select your organization.
  3. In the left sidebar, navigate to Directory > Service accounts.
  4. Click Create service account.
  5. Give the service account a recognizable name (e.g. Waydev Integration) and description, then click Create.

Step 2: Grant product and project access in Jira

For the service account to access Jira issues and projects, it must be granted product access and appropriate permissions.

Grant product access:

  1. Find your newly created service account in the Service accounts list.
  2. Under Product access, toggle on Jira (or Jira Software / Jira Service Management depending on what products you use).

Grant project permissions:

  1. Log in to your Jira site as an administrator.
  2. Add the service account user to the relevant Jira groups or projects.
  3. The service account must have the Browse Projects permission for any project you want Waydev to sync. You can assign this by:
    • Adding the service account user directly to the projects' Project Roles (e.g. as a Viewer or Developer).
    • Or adding them to a group that has global/project read permissions.

Step 3: Create OAuth 2.0 credentials and configure scopes

OAuth 2.0 client credentials authenticate the machine-to-machine connection between Waydev and Jira.

  1. Go back to the Directory > Service accounts list in the Atlassian Admin Console.
  2. Select your service account.
  3. Click the Credentials tab and select Create credentials > OAuth 2.0.
  4. Under Scopes, select the permissions that this credential set will be allowed to use.

Scopes are immutable once the credential is created. If you miss a scope, you must delete these credentials and create a new set.

Required scopes:

Select the following scopes during credential creation:

  • read:me - Used to verify the identity of the service account token during connection tests.
  • read:jira-work - Required to search/list issues, read project boards, worklogs, etc.
  • read:jira-user - Required to identify issue authors, assignees, and map commit users.
  • read:project:jira - Required to read project metadata.
  • read:board-scope:jira-software - Required to sync boards.
  • read:sprint:jira-software - Required to sync sprints.
  • read:issue:jira-software - Required to sync issues.
  1. Click Create.
  2. Save the Client ID and Client Secret immediately. The client secret is only shown once and cannot be retrieved later.

Step 4 (Alternative): Create a service account API token

If you prefer not to use OAuth 2.0, you can authenticate using a Service Account API Token (which uses Bearer Auth).

  1. Find your newly created service account in the Service accounts list.
  2. Click the Credentials tab and select Create credentials > API token.
  3. Give it a label (e.g. Waydev Token), then click Create.
  4. Copy the token immediately (it will not be shown again).

Configuring the integration in Waydev

Depending on your chosen authentication method, select the appropriate tab under the Jira integration options:

Option A: Jira Service Account OAuth 2.0

Provide the generated OAuth credentials:

  • Client ID - The Client ID generated in Step 3.
  • Client Secret - The Client Secret generated in Step 3.
  • Base URL - Your Jira instance base URL (e.g. https://your-company.atlassian.net).

Option B: Jira Service Account API Token

Provide the generated API token credentials:

  • Service Account API Token - The API token generated in Step 4.

  • Service Account Email - The exact email address of the service account itself (e.g. [email protected] or automation@...). Note: This cannot be your personal email address.

  • Base URL - Your Jira instance base URL (e.g. https://your-company.atlassian.net).

Troubleshooting common errors

Error: 401 Unauthorized; scope does not match

  • Cause - The OAuth credentials token does not have the scope required by the endpoint (e.g. read:jira-work, read:me, or Agile boards scopes).
  • Jira boards sync skipped with 401 scope mismatch - If you sync projects successfully but get Unauthorized; scope does not match during board syncs, it means the read:board-scope:jira-software or read:sprint:jira-software scopes are missing.
  • Solution - You must delete the existing credentials under your Service Account in the Atlassian Admin console, create a new set of credentials, and make sure that you check/enable both the Jira and Jira Software scopes listed in Step 3 before saving.

Error: 403 Forbidden

  • Cause - The API token is successfully authenticated and has correct scopes, but the service account user does not have permission to view the projects or issues in Jira.
  • Solution - Ensure the service account has been added to your Jira projects with the Browse Projects permission role.


Updated 18 days ago