Connect your application to Aha! Roadmaps so the team can use roadmap data inside Aha! Builder. You can pull goals, 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.
Click any of the following links to skip ahead:
Prerequisites
Action |
Requirement |
|---|---|
Integration direction |
Read and write |
Integration access |
Depends on the permissions of the user who creates the API key |
Credential type |
Personal API key |
Aha! Builder plans |
All Aha! Builder plans |
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 |
Aha! API keys inherit the permissions of the user who generates them.
Create the key with 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 API key user must have contributor or owner access to the relevant workspaces.
Get your Aha! API key
You will need a personal API key from your Aha! account to connect it to your Aha! Builder application.
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 your secret in Aha! Builder
Once you have your API key, add it to your application in Aha! Builder:
Navigate to your application in Aha! Builder.
Click Configuration in the top navigation bar.
Click the Integrations tab.
Under the Aha! tile, click Create.
In the Subdomain field, enter a descriptive name, such as
AHA\_API\_KEY.In the API token field, paste your API key.
-
Click Ask Elle to integrate.
This saves the secret and opens a chat with Elle, the AI assistant.
Your API key is now available to your application code. Secrets are encrypted and stored securely.
Secrets are environment-specific. If you have both a Preview and a Production environment, you will need to add the secret to each one separately.
Use the integration
Once you save the secret, you can ask Elle to build features that use Aha! Roadmaps data. Elle generates the code to connect to the Aha! REST API with your secret and read or update data in your application.
Read data from Aha! Roadmaps:
"Add a dashboard that shows Aha! goals and progress toward target 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 it is marked 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 API key user. If the key belongs to a user with viewer access, write requests will fail. Use a key from a user with contributor or owner access to the target workspaces.
Update a secret
You can update a secret's value at any time. For example, update it when you rotate your API token:
Navigate to your application in Aha! Builder.
Click Configuration in the top navigation bar.
Click the Integrations tab.
Click Edit next to the secret you want to update.
Enter the new value and click Save.
Remove a secret
To remove an integration secret from your application:
Navigate to your application in Aha! Builder.
Click Configuration in the top navigation bar.
Click the Integrations tab.
Click the More options button (...) next to the secret you want to remove.
Click Delete.
Click OK to confirm.
Removing a secret breaks any features in your application that depend on it. Review your application after removing a secret to confirm it still functions correctly.