Skip to content

Auth

Email OTP_

Seamless sign in with Email OTP authentication in Appwrite. Learn how to provide simple and secure passwordless user accounts.

4 min read

Raw

Email OTP (one-time password) authentication lets users create accounts using their email address and log in using a 6 digit code delivered to their email inbox. This method is similar to Magic URL login, but can provide better user experience in some scenarios.

Send email

Email OTP authentication is done using a two-step authentication process. The authentication request is initiated from the client application and an email message is sent to the user's email inbox. The email will contain a 6-digit number the user can use to log in.

Send an email to initiate the authentication process. If the email address has never been used, a new account is created using the provided userId. Otherwise, if the email address is already attached to an account, the user ID is ignored. Then, the user will receive an email with the one-time password.

import { Client, Account, ID } from "appwrite";
const client = new Client()
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
.setProject('<PROJECT_ID>');
const account = new Account(client);
const sessionToken = await account.createEmailToken({
userId: ID.unique(),
email: 'email@example.com'
});
const userId = sessionToken.userId;

Login

After initiating the email OTP authentication process, the returned user ID and secret are used to authenticate the user. The user will use their 6-digit one-time password to log in to your app.

import { Client, Account, ID } from "appwrite";
const client = new Client()
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
.setProject('<PROJECT_ID>');
const account = new Account(client);
const session = await account.createSession({
userId: userId,
secret: '<SECRET>'
});

After the secret is verified, a session will be created.

Code autofill

Email OTP emails carry an OTP-Token header that binds the code to the website that asked for it:

Plain text
OTP-Token: "123456"; origin="https://app.example.com"

The header is defined by the OTP-Token Internet-Draft. A mail client, browser, or password manager that reads it can offer the code for autofill on the bound origin and nowhere else, so a code your app requested isn't offered on a lookalike site. Support for the header in mail clients and password managers is still early, and the draft may change before it becomes a standard. Appwrite adds the header for you, so there is nothing to configure.

Appwrite takes the origin from the Origin header of the request that sends the code, which Appwrite has already checked against the web platforms registered in your project. The email includes the header only when that origin is:

  • Potentially trustworthy. It uses https, or http on localhost, a *.localhost subdomain, 127.0.0.0/8, or [::1].
  • A bare origin. It has no path, query string, or credentials, and its hostname is ASCII.

When the request has no usable origin, Appwrite sends the same email without the header. This covers calls from server SDKs and server-side rendered apps, which send no Origin, and native apps, whose origins use a custom scheme.

The header is also added to email verification codes, password recovery codes, and MFA email challenges, with the same rules. Appwrite adds it whether the email goes through the default SMTP server or your custom SMTP server. Some email providers rewrite or encode custom headers when they relay a message, so if you use one, check the headers of a received email to confirm OTP-Token arrives intact.

Security phrase

A security phrase is a randomly generated phrase provided on the login page, as well as inside Email OTP login email. Users must match the phrase on the login page with the phrase provided inside the email. Security phrases offer protection for various types of phishing and man-in-the-middle attacks.

By default, security phrases are disabled. To enable a security phrase in Email OTP, enable it in first step of the authentication flow.

import { Client, Account, ID } from "appwrite";
const client = new Client()
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
.setProject('<PROJECT_ID>'); // Your project ID
const account = new Account(client);
const promise = account.createEmailToken({
userId: ID.unique(),
email: 'email@example.com',
phrase: true
});
promise.then(function (response) {
console.log(response); // Success
}, function (error) {
console.log(error); // Failure
});

By enabling security phrase feature, you will recieve phrase in the response. You need to display this phrase to the user, and we recommend informing user what this phrase is and how to check it. When security phrase is enabled, email will also include a new section providing user with the security phrase.

Was this page helpful?

Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.