Connect your application to Aha! Roadmaps so the team can use roadmap data inside Aha! Builder. You can pull initiatives, epics, features, and to-dos into your application to keep work connected to product direction, and write data back to Aha! Roadmaps when your application needs to create or update records.
Select the Aha! tile in the integrations catalog to connect your application to your Aha! account without generating or storing a key. Your application authenticates with Aha! directly rather than through a third party. If your application needs data the connection does not reach, connect with a personal API key instead.
The Aha! connection is available on the Aha! Builder Scale plan. On the Pro and Team plans, connect with a personal API key.
Click any of the following links to skip ahead:
Prerequisites
Action |
Requirement |
|---|---|
Integration direction |
Read and write |
Integration access |
Depends on the Aha! permissions of the user who connects Aha! or creates the API key |
Credential type |
Aha! connection (no key required) or personal API key |
Aha! account |
The Aha! account your Aha! Builder application belongs to. You cannot connect a different Aha! account. |
Aha! Builder plans |
Scale for the Aha! connection. All Aha! Builder plans for a personal API key. |
Required Aha! Builder permissions |
Application owner |
Aha! Roadmaps plans |
Any paid Aha! Roadmaps plan |
Aha! Roadmaps permissions |
Access to the workspaces whose data you want to read or update |
The integration inherits the Aha! permissions of the person who connects it or generates the API key. Connect with an account that has the level of access you want the integration to have.
If your application only needs to display data, a user with viewer access is sufficient.
If your application needs to create or update records, the connecting user must have contributor or owner access to the relevant workspaces.
Connect Aha!
Connect Aha! from your application's configuration. You do not need an API key or a secret.
Click Configuration in your application's navigation bar, then select the Integrations tab.
Select the Aha! tile to open the Connect Aha! dialog.
Under Choose who can use this connection, keep Per app selected.
Click Next, then authorize the connection to your Aha! account.
Once you authorize, the Aha! tile moves to Connected integrations and a chat with Elle opens, so you can plan what to build with your Aha! Roadmaps data.
A Per app connection gives everyone who can use your application one shared connection, and every request runs with the connecting person's Aha! permissions. Everyone using the application sees the same Aha! data, whatever their own Aha! access is. Connect through a user whose access matches what every user of the application should see.
Preview and Production keep separate connections. Test the integration in Preview first, then switch to Production and connect Aha! again when the integration is ready.
To review the connection, select the Aha! tile under Connected integrations. The Manage Aha! connection dialog shows the environment, connection type, connection health, and who authorized it.
Click Reconnect to authorize the connection again, such as with a different Aha! user.
Click Delete to remove the connection. Features that use Aha! data stop working until you connect Aha! again.
If your account's governance rules disable applications' access to the internet, your application cannot reach Aha! data either.
Use the integration
Once you connect Aha!, tell Elle what your application should do with Aha! Roadmaps data. Elle generates the code that reads and updates Aha! Roadmaps records through the connection.
Read data from Aha! Roadmaps:
"Add a dashboard that shows Aha! releases and progress toward their release dates."
"Create a page that lists features in the ACME workspace with their status and assignee."
"Show Aha! to-dos in a prioritized task list grouped by workspace."
Write data to Aha! Roadmaps:
"Create a new feature in the ACME workspace when someone submits a request in this application."
"Update the status of an Aha! to-do when a user marks it complete in this application."
"Add a comment to the linked Aha! feature whenever a user leaves feedback here."
Write operations depend on the permissions of the connecting user. If that user has viewer access, write requests will fail. Connect with a user who has contributor or owner access to the target workspaces.
The Aha! connection uses the Aha! API v3, which does not cover every record type yet. If your application needs records the connection cannot reach, connect with a personal API key, which uses the full Aha! REST API.
Connect with an API key
Use a personal API key if your plan does not include the Aha! connection, or when your application needs data that the connection does not cover. A key gives your application the full Aha! REST API and inherits the permissions of the user who generated it.
Get your Aha! API key
Log in to your Aha! account.
Click your User menu (your avatar in the upper-right corner) -> Settings -> Personal.
Select Developer in the left sidebar.
Click Generate API key.
Enter a descriptive name, such as "Builder integration."
Click Generate.
Copy your API key now and store it somewhere safe. Aha! will not show it again after you close this page.
Aha! Roadmaps support resources |
|---|
Add the key to your application
Add the key as a secret on your application's Secrets tab, then ask Elle to use it to connect to Aha! Roadmaps. Update or remove the secret from the same tab when you rotate or retire the key. Removing a secret breaks any features in your application that depend on it, so review your application afterward to confirm it still works correctly.