AuditBadger Help Center

Heroku Setup Guide

Open in
View as Markdown Open in ChatGPT Open in Claude
M

Maciej Litwiniuk

Last updated on Oct 13, 2026

How to connect a Heroku team or a personal Heroku account to AuditBadger. AuditBadger asks Heroku for read-only access with the read scope. AuditBadger refuses a token with a wider scope and does not store it.

Read-only access can still expose sensitive data

Connecting Heroku can expose sensitive data to AuditBadger, even if your application logs contain no secrets. Heroku's read scope is broader than the metadata needed for compliance checks. Depending on your Heroku permissions and app configuration, API responses can include:

  • Credentials in log-drain URLs, such as passwords or API tokens.

  • Links that may allow source-code downloads or access to build output.

  • Secrets embedded in dyno commands, custom buildpack URLs or other app metadata.

AuditBadger receives these API responses on its servers during connection checks and evidence collection. It removes known sensitive fields before saving evidence. For example, it keeps only the scheme and host of log-drain URLs, discards dyno commands and removes source-code download links. The integration does not follow these links, download source code, read database contents or open log streams.

These safeguards reduce exposure; they do not eliminate it. Filtering happens after AuditBadger receives a response and cannot detect every secret. A credential embedded in a custom buildpack URL path, for example, may remain in collected evidence. If the integration token or AuditBadger's integration service is compromised, data available through the token's Heroku permissions may also be exposed. Any exposed credentials may grant access to other systems, depending on their permissions.

Selecting apps in AuditBadger limits evidence collection, not the token's permissions in Heroku. Heroku does not offer an OAuth scope limited to compliance metadata that excludes source-code links and log-drain credentials. Its OAuth scope documentation explicitly warns that read access can expose credentials in metadata.

Use a dedicated Heroku user with the minimum app access needed, keep secrets out of commands and custom metadata, and revoke the grant when you no longer need it. Connect only if this access is acceptable under your security policy. If your policy requires that AuditBadger cannot receive any source-code links or credentials, this integration does not meet that requirement.

Before you start

  • You need the admin role in AuditBadger.

  • Use a dedicated Heroku integration user. Start with the view permission on only the apps you need to monitor. Some evidence sources may be unavailable with these permissions. The pasted-token option requires a user who does not sign in through SSO.

    • Limit app access in Heroku itself. The app selection in AuditBadger does not restrict what the token can read. Even Heroku's view permission includes code access; it is not a guarantee that source code is inaccessible.

    • Heroku gives each user one budget of API requests. A dedicated user keeps the requests of AuditBadger apart from the requests of your own tools.

  • If you sign in to Heroku through SSO, use Connect with Heroku. Heroku does not let SSO-federated users create authorizations, so the token option does not work for them.

  • A team admin can turn off third-party OAuth access for the team. Then Heroku refuses the calls that Connect with Heroku makes on the apps of that team.

1. Connect

Option A: Connect with Heroku (recommended)

  1. In AuditBadger, go to Account Settings → Integrations. Open Heroku in the Engineering group.

  2. Click Connect with Heroku.

  3. Sign in to Heroku as the integration user. Approve the read-only access request.

  4. Heroku sends you back to AuditBadger. AuditBadger checks the scope of the token before it stores the token.

The Connect with Heroku option shows only when your AuditBadger deployment has a Heroku OAuth client. If you do not see the option, use option B.

Option B: Paste a read-scoped token

  1. Sign in to the Heroku CLI as the integration user (heroku login).

  2. Run this command:

    heroku authorizations:create --scope read --description AuditBadger

  3. Make sure that the output shows Scope: read. Copy the value after Token:. Keep the value after ID:, because you need it to revoke the token.

  4. In AuditBadger, go to Account Settings → Integrations → Heroku. Open Paste a read-scoped token, paste the token and click Connect Heroku.

The token does not expire unless you add --expires-in to the command. AuditBadger checks the scope before it stores the token.

2. Select the Heroku account

When the Heroku user is a member of one or more teams, AuditBadger asks which account to monitor:

  1. Select one team, or select Personal account (the apps that are not in a team).

  2. Click Use this account.

AuditBadger monitors one team or the personal account. When the Heroku user is not a member of a team, AuditBadger connects the personal account immediately.

One evidence source needs a team: Heroku CI Test Runs. AuditBadger does not offer it for a personal account.

If you authorized AuditBadger for a team

When you approve the access request in Heroku, you can authorize AuditBadger for one Heroku team. Heroku then lists AuditBadger in the Team Authorized Applications of that team. Such a token reads only that team, so it cannot list your teams. AuditBadger asks for the team name instead:

  1. Find the team name in the Heroku Dashboard. It is the last part of the team URL: dashboard.heroku.com/teams/NAME. You can also use the team ID.

  2. In Heroku team name, enter the name.

  3. Click Use this account.

AuditBadger reads the team and monitors its apps. There is no personal account option for such a token. If AuditBadger shows "This token cannot read the Heroku team that you entered", examine the team name, and make sure that you authorized AuditBadger for that team.

To change the account later, open Change the Heroku account. When you select a different account, AuditBadger clears the app selection and the production settings.

3. Choose the apps

In the Apps section:

  1. Select the monitoring scope:

    • All apps: AuditBadger adds new apps automatically.

    • Selected apps only: tick each app to monitor. If you tick no app, AuditBadger collects no app evidence.

  2. Check the production setting of each app:

    • An app in the production stage of a pipeline is a production app.

    • An app that is not in a pipeline is not a production app.

    • To change this for an app, select Production or Not production. Follow pipeline uses the pipeline stage again.

  3. Optional: in Allowed regions, tick the Heroku regions where your apps can run. An app in a different region fails the Region Residency check. If you tick no region, AuditBadger only records an inventory of regions.

  4. Optional: in Buildpack allowlist, add the buildpacks that you approved, one on each line (a buildpack name or a URL). AuditBadger always accepts the official heroku/* buildpacks.

  5. Click Save monitoring settings.

Many checks look at production apps only. If AuditBadger finds no production app, these checks do not run, and the evidence shows a warning. Mark your production apps correctly.

4. Check the API access

The API access panel tells you whether every evidence source can run with your connection. At each connection check, AuditBadger reads each supported Heroku API area one time, even if you have not installed its evidence source. These are real API requests and can receive sensitive metadata as described above. When Heroku refuses an area, AuditBadger does not offer the evidence sources that need it, and the panel says "Some evidence sources cannot run with this connection, so AuditBadger does not offer them." AuditBadger never asks for a wider scope.

AuditBadger has no evidence from releases, app webhooks or team members. Heroku shows these areas only to a scope wider than read, so AuditBadger never reads them. Build Provenance records the builds of your production apps and the user who started each build. Access Inventory takes the team role of each user from the collaborators of each app.

After you change the apps, click Check the connection (the button with two circular arrows) to check the access again. The check runs in the background. Reload the page after one minute.

5. Install the evidence sources

  1. On the Heroku page, click Install Evidence.

  2. Select Install to Controls, Install as Subcontrols or Install on Common Controls.

  3. Select the project and the controls, and confirm.

You can also add a Heroku evidence source from a control. AuditBadger offers only the sources that can run with your connection.

What AuditBadger collects

  • Apps: name, region, stack, generation, pipeline and stage, maintenance mode and Private Space.

  • App collaborators: email, team role and app permissions.

  • Builds: status, time, user email, commit SHA, stack and buildpacks.

  • Heroku CI: the number of test runs by result, and whether the commit that runs in production passed.

  • Configuration: custom domains and the name, expiry date and signature type of their certificates. The host of each log drain. Add-on names, services and plans. Dyno counts and sizes. The review app setting of each pipeline.

What the integration does not request

The integration does not request the following data or sessions. This describes its collection behavior, not everything the Heroku token could access:

  • Config vars of apps, releases and pipelines.

  • Releases, app webhooks, team members, team invitations and team settings. Heroku shows them only to a scope wider than read.

  • Add-on configuration values and add-on single sign-on.

  • Database contents, the Heroku Postgres data API and backup download links.

  • Log sessions and log streams.

  • Source-code downloads and build-output streams.

  • Dyno attach sessions.

  • Telemetry drains of Fir apps.

Dyno commands and source-code download links can be present in API responses that AuditBadger receives; they are removed before saving evidence. AuditBadger also calls GET /account during token validation to confirm that Heroku refuses access. If that endpoint is accessible, AuditBadger rejects the token. AuditBadger encrypts its stored integration tokens at rest.

Replace the token

  • Pasted token: open Connection. Paste a new read-scoped token in Replace with a new read-scoped token and click Check and replace. AuditBadger keeps your account, app and region settings. If AuditBadger refuses the new token, the old token stays. After the replacement, revoke the old token in Heroku.

  • Connect with Heroku: open Connection and click Reconnect with Heroku.

Revoke access

  1. In AuditBadger, open the Heroku page. In Disconnect Heroku, click Disconnect.

    • AuditBadger deletes its Heroku tokens and stops evidence collection.

    • The evidence that AuditBadger collected stays.

    • AuditBadger removes the Heroku evidence sources. If you connect again, install the evidence sources again.

  2. Revoke the grant in Heroku. AuditBadger cannot do this for you, because a read-scoped token cannot revoke itself.

    • Connect with Heroku: in the Heroku Dashboard, go to Account settings → Applications. Revoke AuditBadger in Authorized Applications. If you authorized AuditBadger for a team, revoke it in the Team Authorized Applications of that team.

    • Pasted token: run heroku authorizations to find the ID of the token. Then run heroku authorizations:revoke <ID>.

Troubleshooting

When a connection check fails, the Heroku page shows the error. AuditBadger collects no Heroku evidence until a check succeeds. Correct the cause, then click Check the connection.

  • "Paste the token from heroku authorizations:create --scope read" - The pasted text is not a token. Paste only the value after Token:.

  • "Heroku reports that this token can do more than read" - The token has a wider scope than read, or more than one scope. For example, heroku auth:token prints a token with the global scope. Create a token with --scope read and no other scope, or use Connect with Heroku. If an existing connection shows this error, AuditBadger deleted the stored token. Connect again.

  • "AuditBadger could not confirm that the scope of this token is read" - Heroku did not report the scope of the token. AuditBadger does not store a new token whose scope it cannot confirm. For a stored token, AuditBadger keeps the token but collects no evidence until a check confirms the scope. Click Check the connection later. If the error occurs again, contact support.

  • "Heroku rejected the token" - Somebody revoked the token, the token expired, or Heroku did not renew it. Create a new read-scoped token, or click Reconnect with Heroku.

  • "Heroku refused access (HTTP 403)" - Possibly a team admin turned off third-party OAuth access for the team. Ask a team admin to examine this setting. Also make sure that the integration user can see the apps of the team.

  • "This token cannot read the Heroku team that you entered" - The token was authorized for a different team, or the team name is not correct. Use the name from the team URL in the Heroku Dashboard, or the team ID. If necessary, connect again and authorize AuditBadger for the correct team.

  • "This token cannot see the selected Heroku team" - The Heroku user is not a member of the team now. Use a token of a team member, or disconnect and connect again to select a different account.

  • "This Heroku user has almost no API requests left" - Your other tools use the same request budget of this Heroku user. AuditBadger stops when fewer than 250 requests are left. Try again later. A dedicated integration user prevents this problem.

  • "The Heroku sign-in link expired or is not valid" - Start the connection again. Finish the Heroku sign-in in 15 minutes or less, as the same AuditBadger user.

  • "Connect with Heroku is not set up" - Your AuditBadger deployment has no Heroku OAuth client. Paste a read-scoped token.

  • An evidence source is missing - AuditBadger offers only the sources that can run with your connection. Heroku CI Test Runs needs a team. A source is also missing when Heroku refused an API area that it needs: see Refused (403) in the API access panel. To find the cause, give support the refused areas.

  • The evidence warns: "Heroku refused the read-scoped token access to ... the evidence is partial" - Heroku refused a read during the collection. The evidence names the API areas and the apps that AuditBadger could not examine.

  • The evidence warns: "No production app was identified" - Add your production apps to the production stage of a pipeline, or set them to Production in the app list.