Last updated June 16, 2023

Two-factor authentication 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.

An application on your smartphone generates the verification code. To gain access to your account a potential attacker would need your email address, your password, and your phone.

We recommend that 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 also work.

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

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

Setting Up Recovery Options

After you configure your smartphone authenticator app, Heroku prompts 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 and you don’t have access to your recovery codes. SMS backup recovery by phone is strongly recommended to avoid losing access to your account.

Heroku validates your phone number by sending an SMS with a setup code. Sometimes Heroku can’t 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, email 2fa-feedback@heroku.com.

Heroku prompts 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 Interface

After your account has two-factor authentication enabled, you’re asked to reauthenticate the next time that 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, for example, you lose your phone or it’s 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.

After you log in to your account, reconfigure two-factor authentication on the account page.

Recovering From Lock-Out

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

If for some reason you lose access to your two-factor device and your recovery codes, you have three additional ways you can regain access.

1. If you’re logged into Dashboard in a browser, you can turn off two-factor authentication for your account on the Settings page. You’re 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. You’re asked for your password.
3. If you 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, you’re not guaranteed to regain access to your account. For help, email account-lockout@heroku.com. We can only disable two-factor authentication if we can verify your ownership of the account, which isn’t always possible.

Changing Your Mobile Device

If you change to a new mobile device, you must disable two-factor authentication and then re-enable it using the new device. If your old device is still functional, use the authenticator app on the old device to log in. It works even if you’re not connected to the network. If your old device no longer works, 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, it’s possible that you still must reconfigure two-factor authentication. For security reasons, the two-factor configuration isn’t backed up by the Google authenticator app. Other applications can work differently.

Disabling Two-Factor Authentication

You can disable two-factor authentication from the Dashboard account page. For added security, you’re asked to supply your password. You can also disable it from the CLI with this command and your password.

$ heroku 2fa:disable