Aha! Roadmaps | Integration authentication errors

In most cases, once you save your Jira integration configuration in Aha! Roadmaps, you are ready to go — no further configuration needed.

In case you do run into trouble, we have gathered some of the most common issues with integration authentication here, along with recommended solutions.

Often the best place to start in most of these situations is the integration log messages for your configuration. Those messages will help diagnose and solve the problem.

Click any of the following links to skip ahead:

• Project does not exist

• 302 error

• 401 authentication errors

• Jira Cloud 401 authentication errors

• 403 authentication errors

Project does not exist

Symptom

You are trying to authenticate your Jira integration and you see an error message that looks like this:

Project with key ‘XXXX’ either does not exist or you do not have permission to create versions in it

Explanation

This error message indicates that the user account used to authenticate the integration does not have permission to create versions in Jira.

Resolution

When you integrate with Jira, the user account that you use to authenticate with Jira must have adequate permissions to create and modify the fields that you mapped on the Settings ⚙️ Workspace Integrations page.

If you intend to create versions with the integration, the Jira user that you used to set up the integration must have permission to perform this action.

Top

302 error

Symptom

You are trying to authenticate your Jira integration and you see an error message that looks like this:

Remote error for 'installed': Unhandled error: STATUS=302

Explanation

If you see this error in your logs after attempting to add the Jira integration, it's likely that you are using Jira on-premises. The request from Aha! Roadmaps is going to a publicly routable IP but the response from Jira is providing links to internal IP addresses. Since they are internal, Aha! Roadmaps cannot access them and the 302 error is being reported.

Resolution

Please check the error log for any reference to the resource being located and you will likely see an internal (private) IP address. Make sure to follow these recommendations for network configuration and allow listing IP addresses.

Top

401 authentication errors

Symptom

You are trying to authenticate your Jira integration and you see an error message that looks like this:

Remote error for 'installed': Authentication failed: 401

Explanation

This error comes directly from Jira, and it happens when Aha! Roadmaps attempts to use the Jira credentials in the integration for an authentication check.

Resolution

The first (and simplest) troubleshooting step is to confirm that you have correctly entered your username and password in the Configure account step of your Jira integration. If those credentials are correct, then something else might be at fault.

SSO and Jira

The most common source of 401 authentication issues comes from customers attempting to authenticate a Jira integration using SSO credentials. SSO credentials cannot be used for API authentication, though Jira Cloud users have the option to generate an API token to use for authentication.

Authentication errors on a previously working integration

If your integration was previously working and then began generating 401 authentication errors, it means your credentials in Jira most likely changed.

This typically occurs when your system is set to automatically expire passwords on a scheduled basis.

Top

Jira Cloud 401 authentication errors

Symptom

You are using the correct credentials to enable your Jira Cloud integration but are still seeing a 401 authentication error when you attempt to authenticate the integration.

Explanation

In April 2019, Jira began to move away from password authentication for accessing the Jira Cloud API. You must now authenticate with Jira using an API token.

Resolution

API token

If you are using a Jira 2.0 integration, follow these instructions to update your authentication method from user/password to API token for each one of your Jira integrations.

• The first step is to create an API token in Jira. Follow these instructions from Jira on how to create an API token for your user account.

• Navigate to Settings ⚙️ Workspace and select your Jira integration.

If your integration setup uses an integration template, you only need to update the template.

• Navigate to the Configure Account integration step.

• Paste the Jira API token from step 1 into the Password field and save.

For Jira Cloud customers, the Jira user's email address must be used in the Username field.

If you are using a Jira 1.0 integration, you can update the password in the integration settings.

Username

The Username field requires the email address you use to log in to your Jira account, not a username. Confirm that you have used an email address here, then click Test connection to see if you have resolved the issue.

Top

403 authentication errors

Symptom

You are trying to authenticate your Jira integration and you see a 403 error message.

Explanation

If you are a Jira Cloud user, you need to use API tokens rather than passwords for authentication.

If you are a Jira via Connect user, you need to convert your integration to a Jira Cloud integration.

Resolution

For Jira Cloud users, you need to use an API token and confirm that you are using the email address that you use to log in to your Jira account, not a username.

For Jira via Connect users, please contact our Customer Success team so they can help you convert your integration to Jira Cloud.

Top