Two-factor Authentication

Last Updated: 14 April 2015

Table of Contents

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

Enabling two-factor authentication will log you out of all but the current session and re-generate your API key. SSH based Git push is not affected.

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.

Enable two-factor authentication

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

Download an app

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

Scan the code

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

Verify your code

Set up recovery options

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.

Set up phone recovery

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.

Do not use Google Voice or other VoIP numbers for two-factor SMS recovery. If your online identity (your email account, for example) is compromised, attackers may gain access to your VoIP phone account and be able to receive recovery messages and get access to your Heroku account. You should also check that your phone account subscription security is good so that attackers cannot spuriously access SMS messages through an online interface or similar.

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.

After enabling two-factor authentication, download and print your recovery codes and store them in a secure place. If you lose your phone, you can use them to authenticate. For security reasons, Heroku Support may not be able to restore access to accounts with two-factor authentication enabled if you lose your phone, can’t recover with SMS and don’t have access to your recovery codes.

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.

Make sure you have the latest CLI version with two-factor authentication support by running heroku update.

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
Authentication successful.

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, simply 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

If you are locked out due to a two-factor issue, DO NOT reset your password.

To prevent lock-out, always download recovery codes and store them in a safe place. To get recovery codes, go to your account page and click on "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 2 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 API token 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.

If none of these methods work for you, it is not guaranteed that you can regain access to your account. You may file a ticket with support by emailing support@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.

If you are using an iPhone, enable encryption on your iPhone backup and many passwords will be remembered after a restore. Some users have reported success with restoring Google authenticator app this way.

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.