Verifying the User's Email Address and Phone Number

Kii Cloud provides a verification mechanism to check if an email address and a phone number specified by a user are valid. This mechanism will prevent a user from using invalid (i.e., random or other users') email address and phone number upon the user sign up.

You can toggle the verification feature on and off in the developer portal. If the verification is turned on:

  • The users will be able to log in with the email address and phone number only after they are verified.
  • Querying users with the email address and phone number are only possible after they are verified.

End users can log in with their email address or phone number after they click a link included in an email or SMS message sent from Kii Cloud and the verification completes.

An email address or phone number can be shared among multiple users. However, if the verification is turned on, only one user can be verified with a specific email address or phone number. For example, only the first user who clicks a link in a verification email can log in with the email address. The same applies to a phone number.

Logging in with only an email address/phone number

When using the verification feature, you need to ask your users to provide another identifier that does not require the verification upon sign up.

The following table summarizes the verification settings and the required identifiers.

Email Verification Phone Number Verification Required Identifiers
Enabled Disabled Username or phone number, in addition to email address
Disabled Enabled Username or email address, in addition to phone number
Enabled Enabled Username, in addition to email address and/or phone number

For more details on the possible combination of the identifiers and verification settings, please check this table.

In order for the user to receive an email or SMS message for verification, they must have logged in to Kii Cloud. Therefore, your mobile app should provide a login method with an identifier that is not to be verified, such as a username. If you want to avoid providing such a login method, see the next section, "Allowing to log in only with a verified identifier".

Allowing to log in only with a verified identifier

In order to have users log in only with their verified identifier, you need to devise a user registration flow.

When you create a new user in a normal way, the user will be able to log in before they finish verifying their email address or phone number. For instance, suppose that a user creates their account with the email address and username while the email verification is enabled. The user will be able to lo gin with their username even if their email is not verified.

There are a couple of approaches you can take to allow users to log in only with their verified identifier.

  • Using pseudo user

    By extending a pseudo user, you can create a user who can only login with their email address (See Pseudo Users for an overview of the pseudo user).

    1. Create a new user as a pseudo user (i.e., no username, password, or email address)
    2. After the user is created, register an email address and password to turn the account into a "normal user".

    The email address verification will start by the above steps. When the verification is done, the user will be able to login only with their email address.

    In case the user enters a wrong email address in Step 2 or wants to resend the verification email, you can take one of the following approaches:

    • Start over again from Step 1. The previous pseudo user will remain unused in Kii Cloud, but this account will not affect your service since only the user who finishes the verification first will be able to login with the email address.
    • If the login state of the pseudo user is active, execute the APIs for requesting for resending the email verification email or changing the email address.

    Creating a user who can only login with their phone number can be achieved similarly. Sending a verification code notified by an SMS message, however, requires the pseudo user to be logged-in. If the login state of the pseudo user is lost, you need to start over again from Step 1.

  • Using auto-generated username

    Another way to create a user who can only login with their email address is to auto-generate their username randomly.

    1. Generate a random username automatically (e.g., by using a UUID or random string)
    2. Create a new user with the generated username, the user's email address, and password.

    By taking these steps, the auto-generated username will not be disclosed to the user. So the user will be able to login only with their verified email address.

    The approach relies on the randomness of the auto-generated username. If the auto-generated username collides (i.e., there exists a user with the same username), the user registration will fail and you will need to start over the user registration again. When using a random string, please make sure to set a seed correctly to avoid generating the same username on multiple devices.

    Just like the "using pseudo user" approach, the user needs to be logged in (i.e., the login state must be active) to take actions such as requesting for resending verification email and code and changing the email address.

Changing the email address and phone number

You can change the user's email address or phone number by executing the APIs.

If you change the email address or phone number while their verification is enabled, the user will receive a verification email or SMS just like the user registration.

Until the verification is completed, the user can login with the old email address and phone number. For example, a user can re-update their email address or phone number by logging in with the old identifiers (e.g., when they have entered a wrong email address or phone number). The new email address or phone number become active when the verification is completed.

Just for your information, there is a dedicated API for directly requesting the resend of the verification email and SMS. Please use them in your application as needed.