Protect your account with two-factor authentication

Last updated on Nov 22, 2026

Updated for version 6.0.30

Two-factor authentication adds a second step to signing in: after your password, you type a 6-digit code shown by an authenticator app on your phone. Even if someone knows your password, they cannot get in without your phone. This article explains how to turn it on and off, and what to do if you lose your phone.

Your Profile window, Security tab: Two-factor authentication section turned off, with the blue Turn on two-factor authentication button the "Two-factor authentication" section of the "Your Profile" window, "Security" tab, with the "Turn on two-factor authentication" button

Where to find two-factor authentication

On the home screen, click your profile picture at the top right (its tooltip reads "Open your profile") to open the "Your Profile" window, then click the Security tab. The Two-factor authentication section shows whether the protection is on or off.

🔺 Note: the Security tab does not appear on self-hosted servers that sign users in without a password.

Before you start

You need an authenticator app on your phone, for example Google Authenticator, Microsoft Authenticator, Aegis or 2FAS. It shows a 6-digit code that changes every 30 seconds. You also need your account password.

Turn on two-factor authentication

  1. In the Security tab, click Turn on two-factor authentication.
  2. Type your account password, then click Continue.
  3. In your app, add an account by scanning the QR code.
  4. If you cannot scan, type the Setup key into the app by hand (the Copy the key button copies it).
  5. Type the 6-digit code the app shows right now.
  6. Click Turn on.

Two-factor setup screen: numbered steps, QR code, setup key with Copy key and the 6-digit code field the setup screen, with the QR code, the setup key and the "6-digit code" field

Your other devices are then signed out: you will have to sign in again there with your password and a code. The device you are using stays signed in.

Keep your recovery codes

As soon as it is turned on, Celestory shows 10 recovery codes (in the form ABCDE-FGHJK). If you lose your phone, each one lets you sign in instead of the app code. Each code works only once.

The codes are shown only once, and closing the page makes them disappear. Use Copy or Download (the file is called "Celestory recovery codes" and contains your email and the date), then keep them somewhere safe: a password manager, a safe, a piece of paper put away. Tick I have kept my codes to be able to click Done.

Two-factor authentication is on: list of 10 recovery codes, Copy and Download buttons, I have kept my codes checkbox and Done button the "Two-factor authentication is on" screen with the list of codes, the Copy and Download buttons, and the "I have kept my codes" checkbox

See how many codes are left

In the Security tab, Celestory shows "You have N recovery codes left". When you have 2 or fewer left, it suggests generating new ones before you run out.

Generate new codes

  1. Click Generate new recovery codes.
  2. Type your password and a code (the app code, or a recovery code).
  3. Click Generate.

The old codes stop working. Your other devices are signed out, as when you turned it on.

Sign in with a code

  1. Type your email and password as usual.
  2. A screen asks "Enter the code from your authenticator app". Type the 6-digit code shown by the app.
  3. Click Confirm.

Sign-in screen, second step: 6-digit code field, Use a recovery code link and Confirm button the sign-in screen asking for the 6-digit code, with the "Use a recovery code" link

A code works only once: if you have just used the code on screen, wait for the next one (30 seconds at most) before a second operation.

With a recovery code

Click Use a recovery code and type one of your codes. Capital letters and the dash do not matter. To go back to the app code, click Use the code from the authenticator app. The Back to email and password link takes you back to the first step.

Turn off two-factor authentication

  1. In the Security tab, click Turn off two-factor authentication.
  2. Type your password and a code (app code or recovery code).
  3. Click Turn off.

Your account is then protected by your password only. Your other devices are signed out. If you turn it on again later, you start a full setup again, with a new key and new recovery codes.

Attempt limits and lockouts

To stop anyone from guessing a code, Celestory limits attempts.

Situation What happens
5 wrong codes during one sign-in The verification stops: type your email and password again
You wait more than 5 minutes on the code screen The verification expires, same thing
10 failures in a row (codes, or password when turning on, turning off or regenerating codes) The account is locked for 15 minutes

During a lockout, signing in is refused even with the right password, and a message says how long to wait. A success resets the counter, and so does the end of a lockout.

🔺 Note: if you reset your password, two-factor authentication stays on, but all your sessions are signed out.

Troubleshooting

Message Solution
Wrong code Wait for the app to show a new code and try again. Check that your phone's clock is set automatically
The verification has expired Type your email and password again
Account temporarily locked Try again after the delay shown
Wrong password Check it; otherwise sign out and use "Forgot password"
Two-factor authentication is not available The server is not configured: see the box below
The setup is no longer in progress Click Cancel, then Turn on two-factor authentication again

For an error you cannot fix alone, Celestory offers copyable details to send to support (they contain no password or code). See Understanding an error message.

For administrators of self-hosted servers

⚠ Warning: two-factor secrets are encrypted with a key that you give to the authentication server, in the MFA_ENCRYPTION_KEY variable (32 random bytes, as 64 hexadecimal characters or as base64, for example with openssl rand -hex 32). Without this key, nobody can turn on two-factor authentication, and accounts that already turned it on can no longer sign in: the second step is never skipped. Losing or changing the key makes every stored secret unreadable, so keep it like a backup secret. The optional MFA_ISSUER variable sets the name shown by the authenticator app ("Celestory" by default).

See also