← Blog

Guide

Recovery codes, and what an administrator can reset

How recovery codes get you in without your phone, how to make new ones, and who can turn two-step verification off when everything is lost.

This is part of Qorekit 0.3, out now as a beta: download 0.3.0-beta.1. As with any beta, keep a backup of anything you cannot afford to lose.

Phones get lost, broken and replaced. With two-step verification turned on, your recovery codes get you into Qorekit without your phone. If you lose those too, an administrator can help.

This post covers all three cases, from the one you handle alone to the one that needs the command line. If you have not turned on two-step verification yet, start with two-step verification for your account.

What recovery codes are

When you turn on two-step verification, Qorekit shows ten recovery codes. Each lets you sign in once without your phone. They are shown only at that moment, so copy or download them before you leave the page.

Keep them apart from your phone. A password manager, a printed sheet in a drawer or a file on another computer will do. If they sit on the same phone as your authenticator app, losing the phone loses both.

Signing in with a recovery code

  1. Sign in with your email address and password as usual.
  2. When Qorekit asks for the code from your app, choose Use a recovery code instead.
  3. Enter one of your recovery codes.

That code is now used up. Cross it off, or delete it from wherever you keep them, so you know how many are left.

Making new codes

Ten codes last a while, but each is good for one sign-in. You may also want new ones because you think someone has seen your list.

  1. Open the account menu, the button with your name at the top right, and choose Account and security.
  2. Under Two-step verification, choose New recovery codes.
  3. Enter your password.
  4. Copy or download the ten new codes.

The old codes stop working at once, including any you had not used. Throw the old list away.

If you have a new phone, you can also choose Turn off and then turn two-step verification on again from the new phone. Both New recovery codes and Turn off ask for your password.

When everything is lost

Sometimes the phone and the codes are both gone. You can still sign in with your password, but you cannot get past the code. You need someone else to turn two-step verification off for you.

An administrator, or someone who manages users, can do it:

  1. Open Administration › Users and select the person.
  2. Their details say whether they sign in with two-step verification.
  3. Choose Turn off beside it.

The person then signs in with their password alone, and can turn two-step verification on again. Only they can turn it on; nobody can do it for them.

A user manager is someone whose role has the permission Invite, edit and deactivate users. They can turn two-step verification off only for users whose every role they could give themselves. They cannot do it for an administrator. This keeps a user manager from weakening an account that has more rights than they do.

The audit log keeps a record each time two-step verification is turned off for someone.

When the administrator is the one locked out

If no administrator can sign in any more, the command line can do it. Someone with access to the server runs this in the Qorekit folder:

php artisan qorekit:two-factor-reset ada@example.com

It turns two-step verification off for that one account. The administrator then signs in with their password and can turn it on again.

This is the last resort. With two administrators who both keep their recovery codes, you should never need it.

Before you need any of this

A few habits make all of the above rare:

  • Store your recovery codes away from your phone.
  • Make new ones when you are down to the last few.
  • Keep at least two people who can manage users, so one lost phone never blocks everyone.

Read more

The documentation covers two-step verification for your account and what administrators can do. Both arrive with Qorekit 0.3.0.