PlanetScale 2FA: how to set up an authenticator app

PlanetScale is a hosted database platform, so your PlanetScale user account is the key to your databases, branches and connection passwords. It offers multi-factor authentication (MFA) with an authenticator app, and it's strict about recovery: if you lose the app and your recovery codes, PlanetScale says there is no way to get the account back, and it accepts no other proof of identity (PlanetScale). Read the recovery section before you start.

This guide uses Authenticator App - Novaz on iPhone. Any authenticator app that makes time-based codes works the same way.

How we checked this guide: the PlanetScale steps come from PlanetScale's own documentation, linked below, which we read on October 21, 2026. We haven't tested them on a PlanetScale account, so a label may differ slightly. The Novaz steps are checked against the app, version 1.0.5.

Who can turn it on

MFA is a setting for accounts that sign in with an email address and password. If you sign in with GitHub or through your company's single sign-on (SSO), PlanetScale doesn't show the MFA settings at all (PlanetScale). In that case, your protection comes from GitHub or your identity provider. PlanetScale also warns that losing access to your GitHub account means losing access to PlanetScale (PlanetScale).

PlanetScale doesn't document a rule that makes MFA mandatory. It's your choice, though PlanetScale strongly recommends it.

Turn on 2FA with an authenticator app

Do this on a computer if you can, so you can scan the QR code with your iPhone (PlanetScale):

1. Go to your account settings at app.planetscale.com/account.
2. In the Security row, click Set up multi-factor authentication. A pop-up opens with a QR code and a list of recovery codes.
3. In Novaz, tap +, then Scan QR code, and point the camera at the code. If the QR code is on your iPhone's own screen, take a screenshot, tap +, then Choose a photo. See scanning a QR code on the same iPhone.
4. Type the 6-digit code from Novaz into the boxes and confirm it.
5. Click the copy button next to the recovery codes and save them somewhere safe, away from your phone.
6. Click Done to close the pop-up.

Two details to know. First, PlanetScale's documentation doesn't mention a text key you can type instead of scanning, and the screenshot of the pop-up shows only the QR code. Plan on scanning. Second, the written steps and the screenshots use different labels: the text says Setup multi-factor authentication and Validate OTP, while the screenshots show Set up multi-factor authentication and Confirm code. Go by what's on your screen.

Save the recovery codes now

PlanetScale shows the recovery codes only during setup (PlanetScale). Its documentation doesn't describe a way to view them again or make new ones while MFA stays on. If you close the pop-up without copying them, the only fix it documents is to turn MFA off and set it up again, which gives you a fresh set.

Without a Novaz backup (iCloud backup or a backup file), its keys exist only on your iPhone, and the recovery codes are your way back in. Keep them in a password manager or on paper, not only on the phone. More in 2FA backup codes.

Signing in

After you turn on MFA, PlanetScale asks for a code from your authenticator app the next time you sign in, on a second screen after your password. On that screen you can also enter a recovery code instead (PlanetScale). The documentation doesn't say whether you can mark a device as trusted.

You can check when MFA was turned on or off in your security log, which records enabled_mfa and disabled_mfa events and keeps them for 6 months (PlanetScale).

If PlanetScale rejects your code

PlanetScale's documentation has no advice for rejected codes. The usual cause is the iPhone's clock: open Settings > General > Date & Time and turn on Set Automatically. Novaz warns you when the clock is 15 seconds or more off. Other causes are in Authenticator code not working?

If you lose your authenticator

Sign in with one of your recovery codes. That's the whole recovery process. PlanetScale is blunt about it: "PlanetScale will not accept any other method of authentication or identification" (PlanetScale). There's no ID check or support reset to fall back on.

Once you're signed in with a recovery code, turn MFA off and set it up again with a new phone. That replaces your old QR code and recovery codes. See also Lost the phone with your authenticator app?

Changing phones

PlanetScale doesn't describe a separate way to move MFA to a new phone. Using the steps it does document, turn MFA off while you still have the old phone, then set it up again on the new one and save the new recovery codes. With Novaz, you can skip this if you use iCloud backup or keep a backup file: restore your accounts on the new iPhone and the codes keep working. Without one, this is the way to do it. See How to transfer your authenticator app to a new iPhone.

Turning 2FA off

PlanetScale strongly recommends leaving MFA on. To turn it off (PlanetScale):

1. Go to your account settings at app.planetscale.com/account.
2. In the Security row, click Disable next to Multi-factor authentication enabled.
3. Enter a code from your authenticator app or one of your recovery codes.
4. Click Disable.

The QR code you scanned stops working, and so do your old recovery codes. In Novaz, open the PlanetScale account and tap Remove account so you don't mix up old and new entries later.

Official PlanetScale help

• Multi-factor authentication
• Authentication methods
• Security log