Multi-factor authentication (MFA)
| 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.
