Last updated October 10, 2022

Two-factor authentication (2FA) adds an extra layer of security to your Heroku account by asking for a verification code after you sign in with your email address and password.

The verification code is generated by an application on your smartphone. To gain access to your account a potential attacker would need your email address, your password, as well as your phone.

We recommend all users enable two-factor authentication for their accounts.

Enabling two-factor authentication

You can enable two-factor authentication on your Dashboard account page by clicking the Enable two-factor authentication button and following the on-screen instructions.

Download an authenticator app for your smartphone. We recommend Google Authenticator or Authy but other alternatives work too.

Scan the barcode shown on the Dashboard page with the downloaded authentication app.

To validate your device, enter the 6-digit code displayed on your smartphone. Two-factor authentication is now enabled for your account.

Setting up recovery options

After you have configured your smartphone authenticator app, Heroku will prompt you to add and validate a phone number. An SMS can be sent to the phone number during login to recover access to your account in case you lose access to your authenticator app (e.g. if your phone is wiped) and you don’t have access to your recovery codes (see below). SMS backup recovery by phone is strongly recommended to avoid losing access to your account.

Heroku will validate your phone number by sending an SMS with a setup code. Note that Heroku may not be able to deliver messages to your phone number. In that case, skip the SMS setup and be extra diligent when downloading and storing the recovery codes in a safe and accessible place. If you encounter problems setting up SMS recovery, please send a note to 2fa-feedback@heroku.com.

Finally, Heroku will prompt you to download recovery codes. Recovery codes are single-use and can be used as an alternative to 2FA codes delivered via your authenticator app or with SMS.

Using two-factor authentication on the command-line

Once your account has two-factor authentication enabled you will be asked to re-authenticate the next time you use the command-line interface.

You can authenticate with your email address and password followed by the authentication code displayed on your phone:

$ heroku login
Enter your Heroku credentials.
Email: email@example.com
Password: password
Two-factor code: 123456
...

Using recovery codes

If you lose access to your two-factor device, e.g. you lose your phone or it is wiped, you can still log in to your account. When prompted for the second factor after entering your account password, choose “Enter a Recovery Code.” You can then enter one of your recovery codes instead of a token from your two-factor device. Note that each recovery code can only be used once.

Once you’ve logged in to your account, you should re-configure two-factor authentication on the account page.

Recovering from lock-out

To prevent lock-out, always download recovery codes and store them in a safe place, and make sure your SMS number is up to date. To get recovery codes, go to your account page and click View Recovery Codes.

If for some reason you lose access to both your two-factor device (e.g. you lost your phone or it was wiped) and your recovery codes, you have 3 additional ways you can regain access:

1. If you are logged into Dashboard in a browser, you can turn off two-factor authentication for your account on the Settings page. You will be asked for your password.
2. If you have a valid CLI session on your computer, you can use the CLI to turn off two-factor authentication with the command heroku 2fa:disable. Here too, you will be asked for your password.
3. If you have set an SMS number, you can obtain a two-factor code via SMS. Choose “Get a code via SMS” when logging in.

If none of these methods work for you, it is not guaranteed that you can regain access to your account. Please get in touch with us by emailing account-lockout@heroku.com. We can only disable two-factor authentication if we can verify your ownership of the account, which is not always possible.

Changing your mobile device

If you change to a new mobile device, you will need to disable two-factor authentication and then re-enable using the new device. If your old device is still functional, use the authenticator app on the old device to log in. It will work even if you’re not connected to the network. If your old device is no longer working, use your recovery codes or the other recovery methods mentioned above.

Note that even if you restore a backup of your old mobile device on a new device, you may still need to reconfigure two-factor authentication. For security reasons, the two-factor configuration is not backed up by the Google authenticator app. Other applications may work differently.

Disabling two-factor authentication

You can disable two-factor authentication from the Dashboard account page. You will be asked to supply your password for added security. You can also disable it from the CLI with the following command:

$ heroku 2fa:disable

This will also ask for your password.