Heroku credentials: Revoke Leaked Tokens and Rotate Exposed Config Vars

A leaked Heroku token is usually a two-stage incident: the token itself can deploy, scale or delete apps, and with the right scope it can read every config var, which is where Heroku apps keep their database URLs and third-party API keys. Heroku has several credential types with very different lifetimes, from 8-hour OAuth access tokens to direct authorisations and refresh tokens that never expire, plus Heroku Postgres connection URLs that are themselves credentials. This guide shows how to tell those credentials apart, what each one reaches, which signals Heroku's audit trail gives you, and the exact revoke, regenerate and rotate steps from Heroku's Dev Center. It is written for platform and security teams running production on Heroku. For roles, secrets handling and audit logging across Heroku, Netlify and Render, read the Heroku, Netlify and Render PaaS Security Guide first; this page goes deeper on leak response.

Key takeaways

• Identify by prefix and context. Current OAuth tokens are 65 characters and begin HRKU-; older unprefixed tokens are UUID-like and only become prefixed when regenerated; a postgres:// URL in a Heroku app is a database credential.
• Scope tells you if secrets are gone. global, read-protected and write-protected include config vars; plain read and write do not, though embedded credentials such as log drain URLs may still be visible.
• Some tokens never expire. Personal direct authorisations and OAuth refresh tokens have no expiry, so a leak from years ago can still be live.
• Rotate config vars, not just tokens. If the leaked token could read config vars, every secret in them is exposed and must be rotated at its issuer, starting with Heroku Postgres credentials.
• Audit trail arrives late. Heroku's audit trail is Enterprise only and exported as monthly JSON archives up to midnight UTC of the current day, so plan to pull it during an incident rather than rely on alerts.

How identity and access work in Heroku

People sign in to Heroku with mandatory multi-factor authentication or through SSO. The CLI and all automation call the Platform API with a bearer token. Heroku's documentation describes these credential types:

What each scope exposes

The CLI's default authorisation is equivalent to global, so a leaked CLI token or HEROKU_API_KEY should always be treated as exposing config vars for every app its owner can reach.

Admin roles and privileged access

Heroku permissions are set per app and per user. The ones that matter for a leak:

• Deploy: push code, view and edit config vars, scale, roll back and run one-off commands. A token whose owner holds Deploy can read the app's secrets and run code inside it.
• Operate: everything in Deploy plus logs, log drains, restarts and paid add-ons. Log drains are a quiet exfiltration route because they stream application output elsewhere.
• Manage: rename, delete, lock and transfer apps and manage other users' permissions. Combined with a leaked token this is the destructive tier.
• Team admins: can add and remove users, change permissions and revoke or regenerate team authorisations. Responders need a team admin available during an incident.

All team members have View on all team apps by default, which reveals releases and code but not config var values. Keep Deploy and Operate on production apps to the people and pipelines that need them, as the Privileged Access Management Guide recommends for any standing access.

Integrations, API tokens and service accounts

Choosing a credential for automation

Team authorisations cannot perform user-only actions even with global, and they survive staff changes, which makes them the right home for automation. Heroku also shows the token only once when it is created or regenerated, so place it straight into the CI secret store.

Third-party tokens held by Heroku

Heroku itself holds tokens for your other systems, most obviously the GitHub integration. In the GitHub OAuth token breach of April 2022, OAuth user tokens issued to the Heroku Dashboard and Travis CI integrations were stolen and used to list and clone private repositories, and an AWS key found in a cloned npm repository was then used against npm's infrastructure. If Heroku or any connected integration announces a compromise, revoke the GitHub authorisation for the integration, review repository clone activity, and rotate any secrets stored in the repositories it could read. The SaaS and OAuth App Governance Guide covers the governance side.

Logging and detection

Detection coverage

Because Heroku is not listed as a GitHub partner for public repositories, a token pushed publicly is not reported to Heroku by GitHub and will not be revoked for you. Also scan for .netrc files in backups, dotfile repositories and container images, since the CLI falls back to .netrc when no keychain is available and leaves old entries there. See the Git Secret Scanning Guide.

Audit trail signals

Enterprise accounts can export a JSON audit archive per calendar month from Settings (Export as JSON in the Audit Logs row) or with heroku enterprise:audits:export from the enterprise CLI plugin. Entries are not always in time order, so sort by created_at. Events worth hunting after a leak:

• config_change.set and config_change.remove outside your release process.
• collaborator.create and team_membership.create adding unfamiliar accounts.
• code_release.create not matched to a pipeline run, and app_transfer.create or app.destroy.
• trusted_ip.update, which could loosen network restrictions.

Heroku's list has no generic OAuth or API token events and no log drain events, so list authorisations and log drains directly during an investigation. Accounts without Enterprise have no audit trail at all, which makes application and database logs, plus GitHub's own audit log, the main evidence.

Metrics

• Personal direct authorisations in use by automation, trending to zero.
• Team authorisations with expiry of 90 days or less, as a share of the total.
• Integrations holding global or protected scopes.
• Days since the last Postgres credential rotation for each production database.
• Time from a secret alert to revocation and config var rotation.

Leak response: revoke and rotate

1. Classify the credential: HRKU- token, legacy UUID token, CLI token from .netrc, or a Postgres URL. Find the owner and scope with heroku authorizations (add --team=<team> for team authorisations).
2. Revoke the authorisation: call DELETE /oauth/authorizations/{authorization-id}, or for team authorisations use Settings, Team Authorizations, Revoke, which any team admin can do and which is immediate and permanent. Where a pipeline must keep running, use Regenerate instead: the old value stops working at once and you deploy the new one.
3. Regenerate the user's API token: if a CLI token or HEROKU_API_KEY leaked, the user regenerates it in the Heroku web interface (a password change also regenerates it), then removes stale .netrc entries with HEROKU_NETRC_WRITE=true heroku logout.
4. Decide whether config vars are exposed: if the scope was global, read-protected or write-protected, or the token was a CLI token, list the apps the owner could reach and treat every secret in their config vars as exposed.
5. Rotate Heroku Postgres credentials: run heroku pg:credentials:rotate (Classic) or heroku data:pg:credentials:rotate (Advanced), with --all if several credentials were exposed. Heroku updates the config vars on attached apps and restarts them. Without --force it waits up to 30 minutes for open transactions; with --force it kills connections at once, which is right when an attacker may hold a live session.
6. Rotate other config var secrets at their issuers: cloud keys, payment and email provider keys, OAuth client secrets. Update the config vars and let the release restart dynos.
7. Hunt for changes: export the current month's audit archive and look for the events listed above, then review log drains, collaborators and add-ons by hand.
8. Record the cause and fix the source: remove the token from history and images, and document the evidence with the Secrets Rotation Runbook Template.

Hardening baseline

1. Inventory authorisations: list personal and team authorisations, integrations and their scopes; record an owner for each.
2. Move CI to team authorisations: create a team authorisation with the shortest workable expiry, switch the pipeline, verify a deploy, then revoke the personal token it replaces.
3. Reduce scopes: re-authorise integrations with read or write where they do not need secrets.
4. Tighten app permissions: remove Deploy and Operate from people who only need View on production.
5. Separate database credentials: on production plans, give analytics and tools their own Postgres credentials so one leak does not expose the owner role.
6. Rehearse rotation: run a Postgres credential rotation in staging to learn its restart behaviour before you need it in production.
7. Roll back: if a revoked token breaks a job, issue a new narrow team authorisation; never restore the leaked one.

Small teams can stop at team authorisations for CI, scanning for HRKU- and .netrc, and a rotation runbook for Postgres and the main config vars. Larger organisations should use Enterprise audit archives in the SIEM on a monthly schedule, enforce SSO, and review integrations quarterly. Whatever the size, write down in advance which secrets live in each production app's config vars, so that the rotation list after a leak is a lookup rather than an investigation.

Common misconfigurations

• Personal direct authorisations in CI: they never expire and act with the user's full rights.
• Revoking the token but not rotating config vars: anything the token read is still exposed.
• Integrations granted global: a breach at the integrator exposes every secret.
• Old .netrc entries left behind: the CLI does not remove them when it moves to the keychain.
• Everyone uses the Postgres owner credential: rotation then affects every consumer at once.
• Relying on an audit trail you do not have: outside Enterprise there is none, and inside it there are no token events.

Framework mapping

Practitioner checklist

• List every personal and team authorisation with owner, scope and expiry.
• Replace personal tokens in CI with team authorisations of 90 days or less.
• Re-authorise integrations with the narrowest scope.
• Scan repositories, images and backups for HRKU-, legacy tokens, .netrc and postgres:// URLs.
• Keep a runbook for Postgres credential rotation, including when to use --force.
• After any token leak with protected or global scope, rotate config var secrets at their issuers.
• Export audit archives monthly (Enterprise) and check config, collaborator and release events.
• Know who your team admins are and how to reach them out of hours.

Standards and references

• Heroku Dev Center: Heroku OAuth
• Heroku Dev Center: CLI authentication
• Heroku Dev Center: Heroku Postgres credentials
• Heroku Dev Center: App permissions
• Heroku Dev Center: Audit trails for Enterprise accounts
• GitHub Docs: Supported secret scanning patterns
• NIST: SP 800-53 Rev 5, Security and Privacy Controls

Related NHI Mgmt Group resources: Heroku, Netlify and Render PaaS Security Guide · Leaked Credential Response Playbook · GitHub OAuth Token Breach · Secrets Management Guide