Multi-factor authentication

Initialize your Appwrite SDK's Client, Account, and Avatars. You'll use Avatars API to generate a QR code for the TOTP authenticator app, you can skip this import if you're not using TOTP.

import { Client, Account, Avatars } from "appwrite";

const client = new Client();

const account = new Account(client);
const avatars = new Avatars(client);

client
    .setEndpoint('https://cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<PROJECT_ID>') // Your project ID
;

Before enabling MFA, you should display recovery codes to the user. The codes are single use passwords the user can use to access their account if they lose access to their MFA email, phone, or authenticator app. These codes can only be generated once, warn the users to save them.

The code will look like this, display them to the user and remind them to save the codes in a secure place.

{
    "recoveryCodes": [
        "b654562828",
        "a97c13d8c0",
        "311580b5f3",
        "c4262b3f88",
        "7f6761afb4",
        "55a09989be",
    ]
}

These codes can be used to complete the Complete challenge step if the user loses access to their MFA factors. Generate the recovery codes by calling account.createMfaRecoveryCodes().

const response = await account.createMfaRecoveryCodes();
console.log(response.recoveryCodes);

Any verified email, phone number, or TOTP authenticator app can be used as a factor for MFA. Before they can be used as a factor, they need to be verified.

const response = await account.updateEmail(
    'email@example.com',  // email
    'password' // password
);

const res = await account.createVerification(
    'https://example.com/verify-email' // url
);

const response = await account.updateVerification(
    '<USER_ID>',  // userId
    '<SECRET>', // secret
);

const response = await account.updatePhone(
    '+12065550100',  // phone
    'password' // password
);

const response = await account.createPhoneVerification();

const response = await account.updatePhoneVerification(
    '<USER_ID>',  // userId
    '<SECRET>' // secret
);

const { secret, uri } = await account.createMfaAuthenticator(
    'totp' // type
);

const result = await avatars.getQR(
    authenticatorUrl,  // text
    800,  // size (optional)
    0,  // margin (optional)
    false // download (optional)
);

console.log(result); // Resource URL

const promise = account.updateMfaAuthenticator(
    'totp',  // type
    '<OTP>' // otp
);

You can enable MFA on your account by calling account.updateMFA(). You will need to have added more than 1 factors of authentication to an account before the MFA is enforced.

const result = await account.updateMFA(true);

Begin your login flow with the default authentication method used by your app, for example, email password.

const session = await account.createEmailPasswordSession(
    'email@example.com', // email
    'password' // password
);

Upon successful login in the first authentication step, check the status of the login by calling account.get(). If more than one factors are required, you will receive the error user_more_factors_required. Redirect the user in your app to perform the MFA challenge.

try {
    const response = await account.get();
    console.log(response);
} catch (error) {
    console.log(error);
    if (error.type === `user_more_factors_required`){
        // redirect to perform MFA
    }
    else {
        // handle other errors
    }
}

You can check which factors are enabled for an account using account.listMfaFactors(). The returned object will be formatted like this.

{
    totp: true, // time-based one-time password
    email: false, // email
    phone: true // phone
}

const factors = await account.listMfaFactors();
// redirect based on factors returned.

Based on the factors available, initialize an additional auth step. Calling these methods will send a challenge to the user. You will need to save the challenge ID to complete the challenge in a later step.

const challenge = await account.createMfaChallenge(
    'email'  // factor
);

// Save the challenge ID to complete the challenge later
const challengeId = challenge.$id;

const challenge = await account.createMfaChallenge(
    'phone' // factor
);

// Save the challenge ID to complete the challenge later
const challengeId = challenge.$id;

const challenge = await account.createMfaChallenge(
    'totp' // factor
);

// Save the challenge ID to complete the challenge later
const challengeId = challenge.$id;

Once the user receives the challenge code, you can pass the code back to Appwrite to complete the challenge.

const response = await account.updateMfaChallenge(
    '<CHALLENGE_ID>', // challengeId
    '<OTP>' // otp
);

After completing the challenge, the user is now authenticated and all requests will be authorized. You can confirm this by running account.get()

In case your user needs to recover their account, they can use the recovery codes generated in the first step with the recovery code factor. Initialize the challenge by calling account.createMfaChallenge() with the factor recoverycode.

const challenge = await account.createMfaChallenge(
    'recoverycode' // factor
);

// Save the challenge ID to complete the challenge later
const challengeId = challenge.$id;

Then complete the challenge by calling account.updateMfaChallenge() with the challenge ID and the recovery code.

const response = await account.updateMfaChallenge(
    '<CHALLENGE_ID>', // challengeId
    '<RECOVERY_CODE>' // otp
);