eOTP Documentation

Your guide to securing the universe with one-time passwords.

What is eOTP?

eOTP is a secure, easy-to-use one-time password (OTP) solution that adds an extra layer of authentication to your web application. It delivers OTPs via phone or email, rendering a customizable modal for users to enter their code. With minimal setup, eOTP integrates seamlessly and scales to meet your security needs.

Generating an AppCode

To use eOTP, you need an `appCode`, a unique code that authenticates your application with the eOTP API. Follow these steps to generate one:

  1. Log in to your eOTP dashboard at eOTP Login.
  2. Go to the appCode section.
  3. Click Create New appCode and provide a name (e.g., "MyApp-Prod").
  4. Enter your website URL to whitelist (e.g., "https://example.com").
  5. Select a Default Method. This is the default method eOTP will use to deliver the OTP
  6. Optional Select a Backup Method. This is the backup method eOTP will use to deliver the OTP if the person cannot receive the OTP at their default method
  7. Copy the generated `AppCode` and store it securely in your application’s environment variables.
Note: Each `AppCode` is tied to the specific website that you provided and cannot be used across multiple domains.

Integrating eOTP into Your Application

With your `AppCode`, you can integrate eOTP by including the eOTP JavaScript library, initializing it, and starting the OTP verification process. Below is a step-by-step guide.

Step 1: Include the eOTP Script

Add the eOTP JavaScript library to your HTML. This loads the lightweight wrapper that initializes the eOTP system.


<script delay src="https://api.e-otp.com/eotp.js"></script>

Step 2: Add a Container

Create a `<div >` in your HTML where the eOTP modal will be rendered.


<div id="your-eotp-container-id"></div>

Step 3: Initialize eOTP

Call `EmbedOTP.init` to configure eOTP with your `AppCode`, container, and user contact details. This verifies your `AppCode` and prepares the system for OTP verification.


<script>
   EmbedOTP.init({
        appCode: "your-appCode-here",
        container: "#eotp-container",
        msisdn: "+1234567890", // User's phone number
        email: "user@example.com", //  User's email
        onSuccess: function(token) {
            console.log("Verification successful! Token:", token);
        }
    });
</script>
Note: You must provide either `msisdn`, `email`, or both for OTP delivery. For example, If your Default OTP method is
The `init` method returns a JavaScript Promise, which resolves when initialization is complete. Learn more about Promises here.

Configuration Fields:

  • appCode: Your unique `AppCode` from the eOTP dashboard.
  • container: CSS selector for the container where the OTP modal will appear (e.g., "#eotp-container").
  • msisdn: User’s phone number in international format (e.g., "1234567890").
  • email: User’s email address (e.g., "user@example.com").
  • onSuccess: Callback function that receives the verification `token` when the OTP is successfully verified.

Step 4: Start Verification

After initialization, use the returned Promise to call `EmbedOTP.startVerification` and display the OTP modal. This sends the OTP to the user’s phone or email and starts a timer.


EmbedOTP.init({
        appCode: "your-appCode-here",
        container: "your-eotp-container-id",
        msisdn:"Cellphone Number goes here ",
        email: "Email Address goes here",  
        onSuccess: function(token) {
             console.log("Verification successful! Token:", token);
        }
        }).then(() => {
             console.log("Initialization complete, starting verification");
                EmbedOTP.startVerification("#eotp-container");
        })
        .catch(err => {
                  console.error("Initialization failed:", err);
        });
});

What `startVerification` does:

  1. Renders the OTP modal in the specified container.
  2. Sends the OTP to the user’s phone or email using the default delivery method (e.g., WhatsApp, SMS, or email).
  3. Starts a 3-minute timer for the user to enter the OTP.

Step 5: Verify the Token

What is the token?

  • In order to add an extra layer of security, eOTP returns a token for you to verify.
  • This token confirms that the OTP entered was valid and successfully verified.
  • Since browser-side code can be tampered with (e.g. via Developer Tools), the token should not be trusted blindly.
  • For security, always verify the token in your server-side code by sending it to eOTP’s backend for validation.
  • This ensures that access is only granted if the OTP flow was legitimately completed and confirmed.
  • This token is cryptographically signed by eOTP and is your proof that the verification flow was completed legitimately.

When the user enters the correct OTP, the onSuccesscallback receives a `token`. For added security, validate this `token` server-side to confirm the user’s identity.

  
let myToken ="";

EmbedOTP.init({
        appCode: "your-appCode-here",
        container: "your-eotp-container-id",
        msisdn:"Cellphone Number goes here ",
        email: "Email Address goes here",  
        onSuccess: function(token) {
            console.log("Verification successful! Token:", token);
//Verifying the token
//Validate token server-side
            fetch("https://api.e-otp.com/validate-token", {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({ Token: myToken })
            })
            .then(response => {
                if (response.ok) {
                    console.log("Token validated successfully!");
                } 
                else {
                    console.error("Token validation failed");
                }
            })
            .catch(err => console.error("Token validation error:", err));

        }
        }).then(() => {
                            console.log("Initialization complete, starting verification");
                            EmbedOTP.startVerification("#eotp-container");
                    })
        .catch(err => {
                            console.error("Initialization failed:", err);
        });
        

        //Alternatively, you can verify externally from the onSuccess:
Important: Always validate the `token` on your server to prevent spoofing. Client-side validation alone is not secure. See the next section for server-side implementation examples.

Server Side Verification

To securely validate the eOTP `token`, your server should handle requests to an endpoint for example: `https://www.yoururl.com/eotp_verify`. This endpoint can accept the `token` either in the request body (e.g., `{ "token": "your-token" }`) or as a query parameter (e.g., `?token=your-token`). The server then forwards the `token` to the eOTP API (`https://api.e-otp.com/validate-token`) for verification. 

  
                let myToken ="";

                EmbedOTP.init({
                     appCode: "your-appCode-here",
                     container: "your-eotp-container-id",
                     msisdn:"Cellphone Number goes here ",
                     email: "Email Address goes here",  
                     onSuccess: function(token) {
 // Option 1: Send token in request body
                        fetch("https://www.yoururl.com/eotp_verify", {
                        method: "POST",
                        headers: { "Content-Type": "application/json" },
                        body: JSON.stringify({ token: token })
                        })
                        .then(response => response.json())
                        .then(data => {
                             if (data.valid) {
                                 console.log("User verified!");
                             } 
                             else {
                                console.error("Verification failed:", data.message);
                             }
                        })
                        .catch(err => console.error("Error:", err));

// Option 2: Send token as query parameter
                        fetch("https://www.yoururl.com/eotp_verify?token=" + encodeURIComponent(token))
                        .then(response => response.json())
                        .then(data => {
                            if (data.valid) {
                                console.log("User verified!");
                            } 
                            else {
                                console.error("Verification failed:", data.message);
                            }
                        })
                        .catch(err => console.error("Error:", err));
                      }
                    }).then(() => {
                         console.log("Initialization complete, starting verification");
                         EmbedOTP.startVerification("#eotp-container");
                    })
                    .catch(err => {
                                console.error("Initialization failed:", err);
                    });


//Alternatively, you can verify externally from the onSuccess
Note: You’ll need to create this endpoint on your backend — see your specific language example below (Node.js, PHP, C# etc.).

Customizing the Theme

eOTP supports theming to match your application’s style. You can use one of five preset themes or define a custom theme.

Preset Themes: `dark` (default), `light`, `blue`, `green`, `grey`.

<script delay src="https://api.e-otp.com/eotp.js"></script>
<script>
   EmbedOTP.init({
        appCode: "your-appCode-here",
        container: "#your-eotp-container-id",
        msisdn:"Cellphone Number goes here ",
        email: "Email Address goes here",
        theme: "blue"
        onSuccess: function(token) {
                console.log("Verified! Token:", token);
        }
    });
</script>
Note: Theme names must be lowercase (e.g., "blue", not "Blue").

Custom Theme: Override the default styles with a theme object.

<script delay src="https://api.e-otp.com/eotp.js"></script>
<script>
   EmbedOTP.init({
        ...

        theme: {
                background: 'linear-gradient(145deg, #2c3e50, #3498db)',
                textColor: '#ecf0f1',
                buttonBackground: 'linear-gradient(145deg, #e74c3c, #c0392b)',
                buttonTextColor: '#ffffff',
                errorColor: '#e91e63',
                timerColor: '#bdc3c7',
                inputBackground: '#34495e',
                borderColor: '#7f8c8d'
            },

        ...
    });
</script>
Note: Custom theme values must be valid CSS colors (hex or linear-gradient). Invalid values revert to the `dark` theme.

Sample Backend Validation Code

We suggest that you validate the Token on your backend for further security. This step is optional but advised. Here are some code examples:

PHP (using cURL)

`<?php
$token = "your-jwt-token-here";
$url = "https://yourdomain.com/validate-token";

$payload = json_encode(["token" => $token]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Content-Length: ' . strlen($payload)
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['valid']) {
    echo "Token is valid! Session ID: " . $result['sessionId'];
} else {
    echo "Token is invalid.";
}`

C# (.NET HttpClient)

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

public class TokenValidation
{
    public static async Task ValidateTokenAsync()
    {
        var token = "your-jwt-token-here";
        var client = new HttpClient();
        var requestUrl = "https://yourdomain.com/validate-token";

        var payload = new
        {
            token = token
        };

        var content = new StringContent(JsonConvert.SerializeObject(payload), Encoding.UTF8, "application/json");
        var response = await client.PostAsync(requestUrl, content);

        var responseBody = await response.Content.ReadAsStringAsync();
        dynamic result = JsonConvert.DeserializeObject(responseBody);

        if (result.valid == true)
        {
            Console.WriteLine($"Token is valid! Session ID: {result.sessionId}");
        }
        else
        {
            Console.WriteLine("Token is invalid.");
        }
    }
}

Node.js (using axios)


    const axios = require('axios');

const token = "your-jwt-token-here";

axios.post("https://yourdomain.com/validate-token", {
    token: token
}, {
    headers: {
        "Content-Type": "application/json"
    }
})
.then(response => {
    if (response.data.valid) {
        console.log("Token is valid! Session ID:", response.data.sessionId);
    } else {
        console.log("Token is invalid.");
    }
})
.catch(error => {
    console.error("Error validating token:", error.message);
});