Skip to main content

Overview

MFA strengthens security by requiring two or more methods (i.e. authentication factors) to verify your identity. PlanetScale allows users logging in with an email address and password to set MFA as a requirement for logging into the user account.
If you’re authenticating via GitHub OAuth or SSO, MFA settings will not be displayed. To use MFA with an account that signs in with GitHub, first switch to email and password.

Require MFA for an organization

MFA is a per-user setting. Organization administrators can’t require it for members or see which members have it enabled. To enforce MFA across an organization, enable SAML SSO and require MFA in your identity provider. Once SSO is enabled, members sign in through your identity provider, so its MFA policy applies to everyone.

Authentication providers

PlanetScale supports login with a unique time-based one-time password (TOTP) that is generated for your user account by using TOTP apps such as 1Password, Authy, or LastPass Authenticator. You can also add a passkey or a hardware security key. A passkey is saved in a password manager or on your device. A hardware security key is a small USB or NFC device, like a YubiKey, that you plug in or tap when you sign in.

Enable MFA

You can enable MFA for your user account under your PlanetScale account settings.
2
Find the Security row and click the “Setup multi-factor authentication” button.
Click the "Setup MFA" button priority
This will bring up a pop-up modal with a QR code and some recovery codes that you will need to copy.
Pop-up modal with QR code and recovery codes priority
Recovery codes are the only account recovery method accepted when MFA is enabled. If you lose both your TOTP app and the recovery codes, there is no way to regain access to your account.
3
Scan the QR code with your preferred TOTP app. If you can’t scan it, enter the secret shown under the code. Then enter the code from the app.
4
Click Confirm code.
5
Once the generated code is validated, click the Copy button in the recovery codes section.
Copy the recovery codes
Save the recovery codes somewhere secure before you continue. You can generate a new set later from your account settings. Generating new codes replaces the old ones, and the new codes are shown only once.
6
Click Done to close the pop-up modal.

Passkeys and security keys

A passkey is saved on your device or in a password manager, such as iCloud Keychain, 1Password, or Google Password Manager. A hardware security key is a small USB or NFC device, like a YubiKey, that you plug in or tap when you sign in. GitHub and SSO accounts do not get this option. They keep using their identity provider.

Add a key

2
Under Security keys, click Add key.
3
Click Continue and follow the browser prompt. Use a passkey, or insert and touch a hardware security key.
4
Name the key so you can recognize it later. The name is filled in for you, and you can change it.
5
If you already have a second factor, enter an authenticator or recovery code. Then click Add key. If this passkey is your first second factor, save the recovery codes shown after it is added.
You can rename a key later from the same list. Removing a key asks for an authenticator or recovery code. Removing your only key turns multi-factor authentication off.

Sign in with a passkey

On the sign-in page, choose Sign in with a passkey, next to the forgot password link. This signs you in without a password or an authenticator code. The passkey has to verify that it is you, for example with Face ID, Touch ID, a device PIN, or your password manager. That verification counts as both your password and your second factor. A hardware security key that only asks for a touch cannot skip the password.

Sign in with a key after your password

If you enter your email and password instead, the next page asks for a second factor. Click Use a security key instead and follow the browser prompt. A touch-only security key works here. If a passkey is your only factor, you can also enter a recovery code.

Login with two-factor authentication

Once you’ve enabled MFA in your PlanetScale user account, the next time you login, you’ll be prompted to enter your two-factor authentication (2FA) code.
  • Use the OTP code generated by your preferred TOTP app to login to your PlanetScale account.
  • Or click Use a security key instead if you have added a passkey or security key.

Recovery code login

The recovery codes shown during MFA setup are the only way regain access to your account in the event that you lose the device that generates your authentication codes. PlanetScale will not accept any other method of authentication or identification. You can use one of the recovery codes in the place of a TOTP token on the second screen during login. To replace your codes, open account settings, click Recovery codes, and enter a code from your authenticator app or one of your current recovery codes. The new codes replace the old ones and are shown only once.

Disable MFA

We strongly recommend that you do not disable MFA to avoid unauthorized access to your user account.
  • Any devices setup with the QR code for your account will no longer be able to produce valid OTP tokens.
  • Any recovery codes that were generated when MFA was enabled will no longer be valid.
You can disable MFA for your user account under your PlanetScale account settings.
2
Click the Disable button next to “Multi-factor authentication enabled” in the Security row.
Click the "Disable" button
3
Enter an OTP code or one of the recovery codes generated by your preferred TOTP app to confirm.
Disable MFA pop-up modal
4
Click the Disable button to close the pop-up modal.

Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.