Multi-Factor Authentication (MFA) significantly improves account security, but it also introduces the risk of being locked out if you lose access to your second factor. This article covers how to set up resilient recovery options so you can always regain access to your account.
Why recovery planning matters
If you lose access to your authenticator app and have no working recovery method, regaining access to your account requires contacting CircleCI Support and completing identity verification — a process that can take 24–48 hours.
The most common causes of account lockout are:
Losing or replacing the device your authenticator app was installed on.
Deleting or losing access to the Google account used as a recovery email.
Never saving the backup recovery code when MFA was set up.
Save your backup recovery code
When you enable MFA, CircleCI generates a one-time backup recovery code. Save this code somewhere secure and offline — for example, in a password manager or printed and stored safely. This code can be used to log in if you lose access to your authenticator app.
Important: Recovery codes are single-use. After using it to log in, generate a new one immediately from your user settings.
Do not rely on a single recovery path
If your only MFA recovery method is tied to an email address (for example, a Google account), losing access to that email address will also lock you out of CircleCI. To avoid this:
Save your backup recovery code in addition to any email-based recovery.
Ensure the email address associated with your CircleCI account is one you have long-term control over.
Keep your authenticator app backed up. Many authenticator apps (such as Authy or 1Password) support encrypted cloud backup — enabling this means you can restore your TOTP tokens to a new device.
Regenerating your recovery code
You can regenerate your backup recovery code at any time from your user settings while you still have access to your account:
Navigate to your user settings via the user icon in the top corner of the web app.
Under the Multi-factor authentication section, select Add/edit authenticator app.
Enter your password and current OTP code.
Select Regenerate recovery code and save the new code securely.
What to do if you are already locked out
If you have lost both your authenticator app and your recovery code, see our troubleshooting article: Troubleshooting: Unable to Access Your CircleCI Account After Losing Your MFA Device or Recovery Code.
Additional resources
Troubleshooting: Unable to Access Your CircleCI Account After Losing Your MFA Device or Recovery Code
Does CircleCI Support Multi Factor Authentication?
What happens to my active sessions when I reset my password?