Some project spaces require users to login using two factor authentication (2FA). This is an extra security step that requires you to input a token from generated by your phone (via call, SMS, or Google authenticator app) before you can complete your login to CommCare.

Initial Set Up (First Login)

When a web user or web apps user first logs in, they will be prompted to set up their 2FA as seen below. To begin, click "Enable Two-Factor Authentication": 

There are three methods you can use to generate a 2FA token—Google authenticator (an app that runs on Android or iOS smartphones), a phone call, or a text message. Select the method you would like to use for receiving tokens.

NOTE: We highly recommend using Google Authenticator as the preferred authentication method. The Phone call and Text message options are dependent on third party SMS carriers. In the event these carriers may be facing issues / delays, the user may not be able to receive tokens / may face a delay in receiving tokens, and this may result in the user being locked out of CommCare for the period these carriers are facing issues. In that case, the user may have to wait until the third party carrier issue is resolved. Thus, we recommend using Google Authenticator for any user wanting to set up Two Factor Authentication on CommCare HQ, as this is a more reliable method, and avoids the dependency on third party carriers to receive tokens via calls or SMS.


Using Google Authenticator 

If using Google Authenticator, you’ll need to first download the Google Authenticator app from the PlayStore or App Store. Once you install it, you’ll need to confirm your account, and then press the + button on the upper right hand corner.


Click scan barcode, and then scan the QR code CommCare has generated for you. Google Authenticator will produce a token that you can put into the Token box, and proceed. Note that tokens in Google Authenticator change every 30 seconds, so you need to type this in a timely manner.

Using Phone or SMS Options 

These methods are highly discouraged, as they're dependent on third party SMS carriers, and may result in a user being locked out if the third party carriers are facing any issues.


If you select phone or SMS, you’ll be promoted to put in your phone number, including + and the country code.



Once you’ve entered your phone number, you will receive a phone call or SMS with your token.

Generating Backup Tokens

You can also generate backup tokens to use whenever you're unable to generate a fresh token (e.g. you're not near your phone, or you're out of country using a different SIM card). It's always good to keep these on hand for situations where you think you might not be able to access your normal 2FA method.

To generate backup tokens:

  1. Go to the settings widget at the upper right hand corner, that looks like a gear icon 
  2. Select "My Account Settings"
  3. Click on Two Factor Authentication
  4. Click on "Show Codes" under the heading Backup Tokens

NOTE: Backup tokes may only be used once. If you've used all your tokens, please re-generate them by following the method above

Subsequent Logins

Every time you sign into CommCare HQ you will be asked to enter a token. Keep your phone nearby so you can easily get the token from your Google Authenticator app, the phone call, or SMS that CommCare sends you.

If you are using the Google Authenticator app for two factor authentication then you will have 30 seconds to enter the code displayed otherwise a new randomly generated code will be created and the timer will reset.  Please enter the code displayed by the Authenticator app before the 30 second timer expires, but if you miss the first 30 second window it will still be valid for an additional 30 seconds.

For SMS codes, once received please enter them within 2 minutes for the code to be accepted, if you miss this window please resend a new valid code to be entered.

Change your Authentication Method

Users are able to change their authentication method. To do this, please: 

  1. Go to the settings widget at the upper right hand corner, that looks like a gear icon
  2. Select "My Account Settings"
  3. Click on Two Factor Authentication
  4. Select "Re-Set Two Factor Authentication" (see image above). This will make you go through the process of updating your two-factor process. Before doing this, please make sure you have tokens available to confirm your original two-factor, as the system will make you go through the process again.


What happens if you lose your backup tokens?

In the event that a user loses access to their backup token, the user should contact their CommCare HQ admin. The CommCare HQ Admin can retrieve their backup token by following the steps on this help page

  • No labels