Integrate PDQ Connect with Jira

Install the free PDQ app for Jira Cloud to view linked devices, deploy packages, and start remote desktop sessions — all without leaving a Jira issue. The integration automatically surfaces devices that belong to the issue reporter, giving your support team instant context about the end user's machine.

How it works

When you open a Jira issue, the PDQ app reads the reporter's email address and looks it up across all of your configured PDQ tenants. Any device belonging to that person is displayed directly on the issue, so your team can act on it immediately.

The matching flow works like this:

1. A user opens a Jira issue.
2. The app reads the reporter's email address from the issue. (If no reporter is set, it falls back to the issue creator's email.)
3. The app queries every configured PDQ tenant for that person's devices, using the matching strategy you set for each tenant. All comparisons are case-insensitive.
4. All matching devices are displayed in the PDQ panels on the issue.

Each tenant matches one of two ways:

Which one should you use? Start with Logged-on User — it needs no preparation, and it is correct for most fleets, where someone's username is the first part of their email. Switch a tenant to Custom Field if your usernames look nothing like your email addresses (for example jdoe against jane.doe@example.com), or if you already maintain device ownership in a PDQ custom field.

Once devices are matched, you can take action directly from the issue:

• View device details — hostname, OS version, online/offline status, and custom fields are shown at a glance.
• Deploy a package — select any package from your PDQ library and deploy it to the device.
• Open the device in PDQ — jump to the full device details page with one click.
• Launch a remote desktop session — start a Remote Desktop connection to the device through PDQ.

The app adds two panels to each Jira issue: an Issue Panel (above the Activity section) and a Sidebar Panel (in the right-hand context area, always visible as you scroll). Both panels display the same linked device information. Jira admins can enable or disable the sidebar panel from the configuration page — see Admin settings below.

The integration supports multiple PDQ tenants, so organizations managing several environments can surface devices from all of them in a single Jira instance.

Before you begin

Make sure you have the following before starting:

You will also need a custom field on your devices populated with user email addresses, and a way for Jira to authenticate to PDQ. You can authenticate either by authorizing the app with OAuth, which needs no key at all, or with a PDQ API key. Steps 1 and 2 below cover both.

OAuth requires app version 7.1.0 or later. If you installed the app earlier, update it first. Because OAuth adds a new callback module and a new Jira permission, your Jira admin may be asked to approve the updated app before the OAuth option appears.

Step 1 — Create a Custom Field in PDQ (Custom Field matching only)

Where you are: PDQ

You can skip this step entirely if you use Logged-on User matching, which is the default for new tenants. It identifies a device's owner from the user signed in to it, so there is no field to create or populate. Go straight to Step 2.

For Custom Field matching, the integration reads a custom field on each device to determine which user that device belongs to. If you have already created and populated a custom field with user email addresses, you can skip ahead to Step 2.

1. In PDQ, navigate to More → Custom Fields in the left navigation.
2. Click Add Custom Field.
3. Name the field something recognizable, such as emailAddress or Email.
4. For each device, populate this field with the email address of the device's primary user.
   • You can do this manually per device, or use the Import Values feature to bulk-update many devices at once from a CSV file.

Tip: The field name matching is case-insensitive (e.g., emailAddress and EmailAddress will both work), but we recommend noting the exact name you chose for consistency when configuring the integration in Step 4.

For more details, see Working with Custom Fields.

Step 2 — Choose how Jira connects to PDQ

Each PDQ tenant you add to Jira connects one of two ways. Pick one per tenant; you can mix methods across tenants and change a tenant's method later.

Using OAuth

Skip to Step 4, where you will choose OAuth as the authentication method and click Connect. The app reads which PDQ organization your authorization belongs to, so you do not enter an Organization URL either.

Generating a PDQ API key

Where you are: PDQ

1. In PDQ, click the gear icon in the lower-left corner to open Settings.
2. Navigate to the API Keys section.
3. Click Create API Key and give it a descriptive name (e.g., "Jira Integration").
   

4. Copy the API key and store it securely. You will not be able to view it again after leaving this page.

   

Don't see the API Keys section? Your PDQ role may not have API key management permissions. Contact your PDQ admin to enable this in your role's RBAC settings.

Important: If you ever suspect an API key has been compromised, revoke it immediately from the same Settings page and generate a new one.

For more information, see PDQ API.

Step 3 — Install the app in Jira

Where you are: Jira Cloud

1. In your Jira Cloud instance, navigate to Apps → Explore more apps (or visit the Atlassian Marketplace).
2. Search for PDQ.

3. Click Install and follow the prompts to add the app to your Jira site.

   

Once the app is installed, a new PDQ Configuration page becomes available in your Jira admin settings.

Step 4 — Configure the integration

Where you are: Jira Cloud — Admin

1. In Jira, navigate to Jira Admin → Apps → Manage apps → PDQ Configuration.
   
2. You will see a tenant configuration form. Fill in the following fields:

3. Click Test Connection to verify that Jira can communicate with your PDQ tenant.

   

   Successful connection displays this information:

   

   Failed connection displays this information:

   

4. Click Save Configuration.

   

Logged-on User matching, with the Source Field choice it adds:

Custom Field matching, which asks for the field name instead:

Checking the match before you save

The tenant editor's third step, Preview the Match, runs the strategy you just chose against a real email address and shows you which devices come back. Enter an address you can verify — your own is the easiest — and click Run Preview.

This is the fastest way to tell a configuration mistake from a data problem. If the preview returns the devices you expect, the strategy and source field are right. If it returns nothing, the answer is usually one of these:

• Under Logged-on User, the username on the device does not match the first part of the email address. Open the device in PDQ and compare the two directly.
• Under Custom Field, the field name is misspelled or the field is empty on the device. Use Suggest fields to confirm the name.

Connecting a tenant with OAuth

If you chose OAuth as the authentication method, the tenant is connected after you save it. The order matters: the app needs the saved tenant before it can authorize one.

1. Set Authentication Method to OAuth. The Organization URL and API Key fields are replaced by PDQ Connect Organization and PDQ Connect Authorization.

   

2. Click Save Configuration. Until you do, the Connect button stays disabled and reads Save configuration first, then connect this tenant to PDQ Connect.
3. Click Connect. A PDQ sign-in window opens. Sign in and approve the request for the organization you want Jira to read.
   
4. Return to the Jira tab. The status changes from Not connected to Connected, and PDQ Connect Organization fills in with the organization the authorization belongs to.
   
5. Click Test Connection to confirm Jira can reach PDQ with the new authorization.

Approving on behalf of the right organization. The app is bound to whichever PDQ organization you approve it for, and the organization name shown on the tenant card is read back from PDQ rather than typed. If it is not the organization you expected, click Re-authorize and sign in to the correct one.

Switching an existing tenant to OAuth replaces its stored API key, and switching back the other way disconnects the authorization. The page warns you before you save either change. Whichever direction you go, the tenant stops working until you finish the new method.

Adding multiple tenants

If your organization manages multiple PDQ tenants, click Add Tenant and repeat the configuration for each one. The integration will query all configured tenants and display matching devices from each.

Admin settings

The configuration page also includes the following settings:

• Restrict to specific spaces — controls which Jira spaces display the PDQ panels. When enabled, a searchable list of all spaces in your Jira instance appears. Toggle on only the spaces where you want PDQ to be visible (e.g., your IT Service Desk space). When disabled, PDQ appears on all spaces — this is the default behavior.
  
• Sidebar Panel — controls whether the PDQ panel appears in the right-hand sidebar of issues (in addition to the main panel above Activity). This is enabled by default.
• Debug Mode — enables detailed console logging for troubleshooting. When turned on, diagnostic information will appear in the browser console and Forge tunnel output. Keep this disabled during normal use.
  

Step 5 — Verify the integration

Where you are: Jira Cloud

1. Open any Jira issue whose reporter owns a device in PDQ — someone signed in to a device for Logged-on User matching, or someone named in the custom field for Custom Field matching. Your own account is the easiest test.
2. Look for the PDQ panel in the issue sidebar (right side) and above the Activity section.

3. You should see the matching device(s) listed with their hostname, OS, and status.

   

If no devices appear, see the Troubleshooting section below.

Using the integration

Viewing device information

When you open a Jira issue, the PDQ panel automatically looks up the reporter's email address across all configured tenants and displays any matching devices. Device cards show key information at a glance, including hostname, operating system, and online/offline status.

If the issue has no reporter, the app falls back to the issue creator's email address. If neither is available, no devices will be matched.

Deploying a package

1. In the PDQ panel, click Deploy package on the device you want to target.
2. The deployment view shows a “Deploy to” section with the target device. If you have multiple devices, you can switch devices using the dropdown.

3. Use the Search packages field to find and select a package from your PDQ library.

   

4. Click Deploy to initiate the deployment.
   

5. A confirmation message will appear. You can track the deployment's progress in PDQ.

   

The deployment view also provides quick access to Device details and Remote access buttons for the selected device.

Opening a device in PDQ

Click the device name or the View Device Details link to jump directly to the full device details page in PDQ.

Starting a remote desktop session

Click Remote Access to launch a remote desktop session to the device through PDQ's built-in Remote Desktop feature.

Troubleshooting

The PDQ panel does not appear on issues

• Confirm the app is installed by going to Jira Admin → Apps → Manage apps and checking that PDQ is listed and enabled.
• Make sure you have completed the configuration in Step 4 and saved at least one tenant.
• If only the sidebar panel is missing, check that the Sidebar Panel toggle is enabled in the admin configuration page.
• If a Jira admin has enabled Restrict to specific spaces on the PDQ Configuration page, ensure the current space is toggled on in the list. PDQ will not appear on spaces that are not enabled.
• Try refreshing the Jira issue page.
  

No devices found for an issue

Start with Preview the Match on the tenant's editor — enter the reporter's email and see what comes back. That separates a matching problem from a connection problem in one click.

Check first, whichever strategy you use:

• Verify that the issue has a reporter assigned and that the reporter's email address is visible in their Jira profile. If no reporter is set, the app falls back to the issue creator's email.
• Confirm which Matching Strategy the tenant uses. A tenant configured before this setting existed is on Custom Field, even if your newer tenants are on Logged-on User.

On Logged-on User matching:

• Compare the username PDQ reports for the device against the first part of the reporter's email. jdoe will never match jane.doe@example.com — that fleet needs Custom Field matching instead.
• Check that the device actually reports a user. A machine that has never been signed in to, or that PDQ shows with an empty or N/A user, matches nobody by design.
• If the device is powered off or unattended, its current user may be empty. Try Source Field → Last Logged-on User, which uses the last person to sign in.
• Under Auto, a device that reports a current user is judged on that user alone. If someone else is signed in to the reporter's machine, it will not match the reporter.

On Custom Field matching:

• Check that the custom field name in the integration configuration is spelled correctly and matches the custom field name in PDQ. Use Suggest fields to list the names that exist on the tenant.
• Confirm that the device(s) in PDQ have the custom field populated with the reporter's email address. A field left blank, or filled with a placeholder such as N/A, is treated as unknown rather than as a match.

If nothing above applies:

• Ensure the tenant's credentials are still good — a valid API key that has not been revoked, or an OAuth tenant that still reads Connected.
• Try enabling Debug Mode in the admin configuration page and check the browser console for more detailed error information.

"No PDQ tenants configured" error

Navigate to Jira Admin → Apps → Manage apps → PDQ Configuration and verify at least one tenant is configured and saved.

Package deployment fails

• Verify the API key has sufficient permissions for deployments.
• Check that the target device is online in PDQ.
• Review the deployment logs in PDQ for detailed error information.

Test Connection fails during configuration

On an API Key tenant:

• Double-check the Organization URL format. It should look like app.pdq.com/your-org-name/devices.
• Confirm the API key is correct and has not expired or been revoked.

On an OAuth tenant:

• Check the status next to the Connect button. A tenant that reads Not connected has never been authorized — save the tenant, then click Connect.
• If it reads Needs re-authorization, click Re-authorize and sign in to PDQ again. See the section below.
• If you saved the tenant but the Connect button never returned to Connected, the sign-in window may have been closed before PDQ finished redirecting back. Click Connect and let the window finish on its own.

On either method:

• Ensure your network allows outbound HTTPS connections to *.pdq.com, including auth2.pdq.com, which handles OAuth sign-in.

An OAuth tenant says "Needs re-authorization"

The app refreshes its own access in the background, so a healthy connection stays connected without anyone touching it. A tenant asks for re-authorization when PDQ stops accepting that refresh — most often because the authorization was revoked in PDQ, the approving user's PDQ access was removed, or the organization's OAuth applications were reset.

Devices will not load for that tenant until it is reconnected. To fix it, open Jira Admin → Apps → Manage apps → PDQ Configuration, edit the tenant, click Re-authorize, and sign in to PDQ. Other tenants are unaffected — each one holds its own authorization.

Cannot access the PDQ Configuration admin page

If you are a Jira administrator but receive an “Admin access required” error when navigating to Jira Admin → Apps → Manage apps → PDQ Configuration, your account may not have been recognized as an admin.

This was a known issue in versions prior to v6.3.0 affecting users whose admin rights came through certain Jira Cloud groups (such as org-admins) rather than via a direct Jira administrator role. Starting in v6.3.0, the integration uses Jira’s native ADMINISTER permission check, which correctly identifies all Jira administrators regardless of which group grants them that role.

To resolve:

• Update the PDQ app to v6.3.0 or later. In older versions, the integration relied on a fixed list of admin group names (site-admins, org-admins, jira-administrators, system-administrators) which may not have matched your Jira configuration.
• If you are on an older version and cannot update immediately, ask a user who is a member of one of the groups listed above to perform the configuration on your behalf.
• If the issue persists after updating, ensure your Jira account has the Administer Jira global permission assigned (directly or via a group) in Jira Admin → System → Global permissions.

Security and privacy

The PDQ app requests only the minimum permissions necessary to function. Here is what the app can and cannot do:

What the app can read:

• Issue details (summary, reporter) to identify the end user.
• User profile information and email addresses for device matching.

What the app can write:

• The app requests permission to write to Jira work items for one optional feature, deployment follow-up, which posts the result of a deployment as a comment and can close the issue when the deployment succeeds. That feature is turned off in the current release, so the app does not add comments to your issues or change their status. Nothing else in the app writes to Jira.

What the app cannot do:

• It cannot delete Jira issues, comments, or other data.
• It cannot access any Jira data outside of the issues you view.

How your data is stored:

• Your PDQ API key is stored using encrypted secret storage provided by the Atlassian platform. It is never exposed in logs or visible to non-admin users.
• For OAuth tenants, the same encrypted secret storage holds the access and refresh tokens instead of a key. Tokens are never shown in the admin page, written to logs, or sent to the browser — only the organization name and the connection status are. PDQ issues a new refresh token each time the app refreshes its access, so a token read from a backup is of no use.
• An OAuth authorization can be revoked from PDQ at any time, which cuts the app's access immediately without anyone editing the Jira configuration. The tenant then reports Needs re-authorization.
• The app stores tenant configuration (organization URL, match field name) in Atlassian's app storage. No Jira user data is stored outside the Atlassian platform.

Technical details — what the app requests in PDQ (OAuth):

When you authorize an OAuth tenant, PDQ shows you the access the app is asking for. It requests read access to devices, packages and custom fields, and the ability to start deployments — the same operations an API key needs for the app to work. It does not ask for anything that can change or delete your PDQ data beyond starting a deployment you asked for from an issue.

Technical details — Jira permission scopes:

Known limitations

• Jira Cloud only. The integration is not compatible with Jira Data Center or Jira Server.
• API rate limits. The PDQ API allows 300 requests per 2 minutes per organization. For very large device inventories, the initial load on an issue may take a few extra seconds while the integration paginates through your full device list. There is no limit on the number of devices or packages supported.
• OAuth needs app version 7.1.0 or later, and an approved update. OAuth relies on a callback the app registers at install time, so an install that has not been updated and re-approved since 7.1.0 will not offer the OAuth option. Existing API key tenants keep working untouched in the meantime.
• One user per device. Either strategy resolves a device to a single person, so a shared machine only ever matches one reporter. Under Custom Field that is whoever the field names; under Logged-on User it is whoever is signed in (or signed in last). Devices with no user at all — kiosks, servers, lab machines — match nobody under Logged-on User, and need the custom field if you want them to surface on tickets.
• Logged-on User matching assumes usernames resemble email addresses. It compares the username to the part of the email before the @. If your accounts are named on a different scheme, use Custom Field matching for that tenant.

FAQ

Is the Jira integration free? Yes. The PDQ Jira app is free to install and use from the Atlassian Marketplace. 

Can I use this with multiple PDQ organizations? Yes. The integration supports multi-tenant configuration. Click Add Tenant on the configuration page and add as many PDQ tenants as you need. Devices from all tenants will appear together on each issue.

Should I use OAuth or an API key? Use OAuth if you can. There is no key to store, copy between systems, or rotate, and you can revoke the app's access from PDQ without touching Jira. Choose an API key if your PDQ role cannot approve OAuth applications, or if you have not yet updated the app to 7.1.0. Both give the app the same abilities inside PDQ.

Do I need an Organization URL when using OAuth? No. The field is not shown for OAuth tenants. The app reads which PDQ organization your authorization belongs to and displays it on the tenant card, and it uses that organization for the "Open in PDQ" links on each device.

Can I use OAuth for one tenant and an API key for another? Yes. The authentication method is set per tenant, and each tenant holds its own credentials. A problem with one tenant's authorization does not affect the others.

What happens if the OAuth authorization is revoked in PDQ? That tenant's devices stop loading and the tenant shows Needs re-authorization on the configuration page. Click Re-authorize and sign in to PDQ again. Nothing else needs reconfiguring — the match field and other settings are kept.

How does device matching work? The app reads the Jira issue reporter's email address and compares it, case-insensitively, against every device in every configured tenant. What it compares depends on the tenant's Matching Strategy. Under Logged-on User — the default for new tenants — it compares the part of the email before the @ against the user signed in to the device, ignoring any DOMAIN\ prefix or @domain suffix. Under Custom Field it compares the full email address against a custom field you maintain on each device. All matching devices are displayed. If no reporter is set, it falls back to the issue creator's email.

Do I still need a PDQ custom field? Only if you use Custom Field matching. Logged-on User matching reads information PDQ already collects, so there is nothing to create or keep up to date.

Can I tell which field matched a device? Yes. Turn on the Matched On display field in the configuration page, and each device on the issue shows what produced the match — the custom field, the current user, or the last logged-on user. This is worth enabling while you are tuning a tenant's strategy.

Can I test matching without opening a ticket? Yes. In the tenant editor, use Preview the Match: enter an email address, click Run Preview, and the page lists the devices that address resolves to right now.

What if a reporter has multiple devices? All devices that match the reporter's email will be displayed. You can select which device to deploy to or connect to from a dropdown in the panel.

Can I limit PDQ to specific Jira spaces? Yes. On the PDQ Configuration page, enable Restrict to specific spaces. A searchable list of all spaces in your instance will appear — toggle on the ones you want. PDQ will only be visible on enabled spaces. If you leave this setting disabled, PDQ appears everywhere (the default).

Can I change how a tenant matches devices? Yes, and each tenant is independent. Navigate to the admin configuration page in Jira (Jira Admin → Apps → Manage apps → PDQ Configuration), edit the tenant, and change its Matching Strategy — or, if you are staying on Custom Field, just update the Email Match Field ID. Run Preview the Match before saving to confirm the change does what you expect.

I see "Admin access required" errors on the configuration page. Only Jira administrators can access the PDQ Configuration page. Your account must have the Administer Jira global permission, which you can check in Jira Admin → System → Global permissions. See the Cannot access the PDQ Configuration admin page troubleshooting section above for more details.

Related articles

• PDQ API
• Working with Custom Fields
• Integrate with Freshdesk (Freshworks)