A secret is a sensitive configuration value your application needs but should never expose, such as an API key, an access token, a connection string, or a password for an external service. Aha! Builder stores secrets separately from your application code and encrypts them at the application layer, so neither the code Elle writes nor your server logs reveal them.
Secrets are available on all Aha! Builder plans: Pro, Team, and Scale.
To open the Secrets page, click Configuration in your application's navigation bar and select the Secrets tab.
Click any of the following links to skip ahead:
Prerequisites
Action |
User permissions |
|---|---|
Add and manage application secrets |
Account, billing, and customization administrators cannot add or change a secret unless they are also an owner of the application. Governance administrators on the Aha! Builder Team and Scale plans can review any application's secrets from the governance page.
When to use a secret
Not all integrations require creating a secret. The integrations catalog handles authentication for more than 3,000 services, so you never see a credential. Reach for a secret when the catalog is not the right fit:
The service is not in the catalog. Search or scroll first, since the catalog reaches well beyond the initial tiles shown on the page. If your tool really is missing, store its credential on this page and ask Elle to build the connection.
You want your application to authenticate as itself. A secret connects your application directly to the service, without Pipedream.
Aha! Builder uses Pipedream as a connection layer between your application and the services in the catalog. Pipedream handles the authentication flow for each service, which is usually the slowest part of setting up an integration. You choose a tool, sign in to it once, and then describe what you want the integration to do.
You are connecting to Aha! Roadmaps. Store a personal API key as a secret to give your application access to the Aha! REST API.
Your application needs a value that is not an integration at all, such as a signing key or a webhook URL.
Add a secret
Generate the credential in the external service first, then bring it here. Most services show a key only once, so copy it before you leave that page.
Click + Add a new secret to open the Add custom secret dialog.
In the Secret name field, enter the name your application code will reference. Standard practice is to use capital letters with underscores — for example,
STRIPE_API_KEY— but it is not required.Paste the credential into the Secret value field.
Click Save.
Your application code references each secret as an environment variable. When you add, update, or remove a secret, the change takes effect the next time your application restarts in that environment (Preview or Production).
Use a secret in your application
Saving a secret makes the value available. Elle, the AI assistant, builds behavior around it.
Click the Elle icon in your application.
Describe what you want the application to do and name the secret it should use. For example: "Use the
STRIPE_API_KEYsecret to list this month's payments on the billing page."Review the result in Preview before you deploy.
Elle reads the secret's name, not its value, so you can reference a secret in a prompt safely. Never paste the credential itself into the Elle panel.
Manage existing secrets
The Secrets page lists every secret you have added and masks each value except for its last few characters.
Copy a value to your clipboard when you need it for another purpose.
Update a value when you rotate a credential in the external service.
Remove a secret you no longer need.
Removing a secret breaks any part of your application that depends on it. Review your application after removing one to confirm it still works.
Preview and production environments
Preview and Production maintain separate sets of secrets. When you add a secret in one environment, it does not exist in the other.
Add the secret to Preview while you build and test.
Add it again to Production before you deploy, or the deployed application will not be able to reach the service.
Use a test credential in Preview and a live credential in Production where the service offers both.
Aha! Builder shows an extra warning before you change a production secret, to help prevent disruptions for live users.