Multi-factor authentication (MFA)
1 month ago
| MFA is currently optional. Starting December 1, 2025 MFA will be required if you log in to CircleCI with email and password. |
Multi-factor authentication (MFA) for CircleCI is available if you sign in to your CircleCI account using email and password. If you use a social login method to access your CircleCI account (such as GitHub or Bitbucket), you can use your login provider’s MFA offering.
Introduction
MFA is an additional layer of security for your CircleCI account. We strongly recommend that you set up and enable it. With MFA enabled, an additional verification step is required to access your account and make changes to account authentication settings, such as email or password. This means that even if your account password is compromised, only someone with access to the additional verification factor can access the account. The additional verification step takes the form of providing a one-time password (OTP).
Set up MFA
To configure MFA on your account, follow these steps:
-
In the CircleCI web app, select your profile from the upper right corner, then select User Settings.
-
Select Password & authentication from the sidebar.
-
On the Password & authentication page, in the Multi-factor authentication section, select Add authenticator app. MFA is marked as Not enabled until a factor is added.
-
Input your password at the password prompt.
-
At the Add authenticator app prompt, scan the provided QR code using an authenticator app or browser extension. Then verify the code generated by the app, by inputting it into the provided text box.
-
At the next screen, you are provided with the MFA recovery code. You must copy this code and save it somewhere safe. This code will only be displayed once and is the last resort for accessing your account in the event that you lose access to your MFA factor. Without this code, you would lose access to your account.
-
You may close the window to complete the setup. When MFA is successfully configured, it is marked as Enabled on the Password & authentication page.
Using MFA on your account
Once you have MFA enabled, then you must provide a second verification factor whenever you log into your account.
You will also be asked to provide a second factor whenever you attempt to change the authentication settings of your account (for example updating your email or password).
Currently CircleCI supports MFA using authenticator applications only. Once you have configured MFA, as per the previous section, then you must use the OTP generated by the application whenever this is requested in the CircleCI web app. The OTP will be displayed in the authenticator app, and you must input this code when prompted in the CircleCI web app.
MFA recovery codes
| If you have MFA enabled, and lose access to your MFA factor and recovery code, then you will lose access to your account. You must ensure that you do not lose the recovery code. |
If you lose access to your MFA factor (for example, by losing access to the authenticator application), you may use the recovery code as a second factor instead. A recovery code may only be used once, after which a new recovery code is generated and shared with you in the CircleCI web app. Whenever a new recovery code is generated, it is important to always save it somewhere safe.
It is also possible to intentionally regenerate your MFA recovery code. To do this, follow these steps:
-
In the CircleCI web app, select your profile from the upper right corner, then select User Settings.
-
Select Password & authentication from the sidebar.
-
On the Password & authentication page, in the Multi-factor authenticationsection, select Add/edit authenticator app.
-
Input your password at the password prompt.
-
Input your OTP at the OTP prompt. Once these have been successfully submitted, your OTP ID and recovery code ID will be displayed.
-
Select the button to Regenerate recovery code on the recovery code row.
-
At the prompt to regenerate the recovery code, select
Yes, regenerate code. This will generate a new code and invalidate the previous recovery code. Store the new code somewhere safe. It will not be displayed again.
FAQs
I have lost access to the device which has my authenticator app. What should I do now?
We strongly recommend that you save your recovery code somewhere secure, for this reason. If you have lost access to your second authentication factor, you can use the recovery code to authenticate. Then you can add a new MFA factor and delete the one which you can no longer access.
I have a new phone and don’t want to lose my MFA factor. What should I do?
If you have a new phone or MFA device, check the documentation of the authenticator app you are using for advice on how to transfer codes. Many authenticator apps support transferring codes to a new device.
Can I use the same authenticator app for multiple accounts?
Yes, most authenticator apps support multiple accounts. You should check the documentation of your authenticator application to confirm.
My authenticator codes have stopped working when I try to use them. What should I do?
If your authenticator codes are not working, this can be an indicator that your authenticator app is out of sync. First check that the time on your device is up-to-date. If the authenticator app you are using does not automatically sync time, check whether there is a setting to re-sync it. If you continue to have issues and are unable to use the OTP to authenticate, you may use your recovery code to authenticate instead. You can then remove and re-add the MFA factor.