Skip to content

Help

Two-factor authentication: set up, security keys, recovery codes, lost device and step-up prompts

Tested with:Databasezy API v1 · zb CLI 0.1

Two-factor authentication (MFA) on Databasezy uses an authenticator app or a security key, with recovery codes as a backup. It is optional for most organizations, but it is required to reveal database credentials, open a writable SQL console, delete a database or create an API key, because those actions need a second factor from the last 15 minutes. Turn it on under Account settings → Two-factor authentication and save your recovery codes somewhere safe.

  1. In the portal, open your account menu and choose Account. This opens Account settings.
  2. In the Two-factor authentication card, under Authenticator app, scan the QR code with an authenticator app (any app that supports TOTP codes). If you cannot scan it, choose Copy key and enter the key in the app.
  3. Enter the 6-digit code the app shows and choose Verify and turn on.
  4. Under Recovery codes, choose Generate recovery codes, then Download .txt or Copy codes, store them in a password manager or another safe place, and choose I saved them: turn on recovery codes. The codes are shown only this once; if you lose them, generate new ones (the old ones stop working).

Once it is on, every sign-in asks for a code after your password, and the portal, CLI and API only accept the session after you enter it.

A security key is a hardware key (for example a YubiKey) or your device’s built-in authenticator (fingerprint or face unlock). It works as a second factor after your password, like the authenticator app.

  • Add one: in Account settings → Security keys, enter a name for the key, choose Add security key and touch or unlock the key when your browser asks.
  • Sign in with it: after your password, choose Use security key and touch or unlock the key.
  • Remove one: choose Remove next to the key. A removed key can no longer be used to sign in.

Passkeys (signing in without a password) are not offered yet.

Changing your email, password, two-factor authentication or security keys needs a sign-in from the last 15 minutes, so a stolen session cannot take over your account. The top of Account settings says until when you can make these changes. After that, saving one of them shows Sign in again to save this: sign in, you come back to the same section, and you make the change again. Your name and your sessions can be changed at any time.

  • Everyone who wants to do sensitive things. Revealing or rotating credentials, writable SQL consoles, deleting or erasing a database, closing the organization, and creating API keys, service-account keys or SSH keys all need a second factor completed in the last 15 minutes. Without two-factor authentication these actions are refused.
  • Every member of an organization that requires it. Enterprise organizations, and any organization that signed the BAA for secure hosting, require two-factor authentication from all members. A member without it is refused with 403 mfa_required for that organization and cannot accept an invitation to it.

“multi-factor authentication required: sign in again with your second factor”

Section titled ““multi-factor authentication required: sign in again with your second factor””

This is the 403 mfa_required problem. The portal handles it for you: it sends you to sign in again with your second factor, then back to the page you were on. Try the action again afterwards. It happens when:

  • your last second-factor check was more than 15 minutes ago and the action is a sensitive one (above);
  • your organization requires two-factor authentication and the session did not use it.

If you have no second factor yet, the portal sends you to Account settings → Two-factor authentication to set one up instead, with a link back to the page you were on.

“recent sign-in required: sign in again to confirm it is you, then retry”

Section titled ““recent sign-in required: sign in again to confirm it is you, then retry””

This is 403 reauth_required. It asks for a fresh sign-in, not a second factor. You see it when changing or cancelling the plan more than 15 minutes after you signed in without two-factor authentication, or after our security team asked for a fresh sign-in on your account. Sign in again and retry.

I lost my phone, my authenticator app or my security key

Section titled “I lost my phone, my authenticator app or my security key”
  1. On the sign-in page, enter your email and password as usual.
  2. At the second-factor step, use another second factor you still have: your security key, your authenticator app, or one of your saved recovery codes (each code works once).
  3. Go to Account settings. Remove the lost security key under Security keys, or set up the authenticator app on your new device under Two-factor authentication, and generate a fresh set of recovery codes.

If you have no other second factor and no recovery code, you cannot complete the sign-in yourself, and resetting your password does not remove the second factor. Email [email protected] from your account’s address and say which organization you belong to. This is much slower than using a recovery code, so keep your codes safe.

Authenticator codes depend on the time on your device. Turn on automatic date and time on your phone and try a new code. Make sure you are reading the entry named Databasezy in your app.

You can remove the authenticator app and your security keys under Account settings, but you will no longer be able to do the sensitive actions listed above, and an organization that requires two-factor authentication refuses your sessions. API keys are not affected by your two-factor settings; protect them with narrow scopes and an expiry (API keys).

Search the help center or ask the assistant in the portal Help panel. If that does not solve it, open a support ticket from the portal (Help → Open a ticket, category account) and include the exact error text, the action you were trying, your browser and the time in UTC. If you cannot sign in, email [email protected] instead. Never paste passwords, authenticator or recovery codes, connection strings with passwords, API keys or patient data (PHI) into a ticket. See How to get help.