Skip to main content

​
The “Usher” Analogy

To understand why verification is necessary, think of OTP Edge like a theater:
  1. The Box Office (/verify-otp): You give them the OTP code, and they give you a Ticket (the Identity Token).
  2. The Usher (Your Backend): The Box Office is outside. To get to the user’s data (the seat), you must show the Ticket to the Usher.
  3. The Check: If the Usher doesn’t check the signature on the ticket, anyone could walk in with a fake piece of paper and claim to be a valid user.
OTP Edge does not return user details in plain text upon success. You must “unlock” the token to see who just logged in.

​
Standard Verification Flow

OTP Edge uses the RS256 algorithm. We provide a JWKS (JSON Web Key Set) endpoint that allows your application to fetch and cache our public keys automatically.

​
Verification Examples

import * as jose from 'jose';

const JWKS_URL = 'https://otpedge.com/.well-known/jwks.json';

async function verifyIdentity(token) {
  try {
    // 1. Create a remote JWK Set (handles caching and rotation)
    const JWKS = jose.createRemoteJWKSet(new URL(JWKS_URL));

    // 2. Verify the token signature and expiration
    const { payload } = await jose.jwtVerify(token, JWKS, {
      issuer: 'otpedge.com',
      algorithms: ['RS256']
    });

    // 3. Token is valid!
    console.log('Verified User:', payload.phone);
    return payload;
  } catch (error) {
    console.error('Invalid Token:', error.message);
    throw new Error('Authentication failed');
  }
}

​
Handling Token Expiration

OTP Edge Identity Tokens are intentionally short-lived (valid for exactly 10 minutes from the time the OTP is verified). This narrow window ensures that if a token is intercepted, it cannot be used indefinitely. If your backend verification fails with a TokenExpiredError (or equivalent in your library), the identity token is no longer valid. Recommended Retry Flow:
  1. Do NOT accept the token: Deny access to the protected route.
  2. Prompt for Re-authentication: Redirect the user back to your login/verification screen.
  3. Re-trigger OTP: The user must request a new OTP code to generate a fresh identity token.
There is no “refresh” mechanism for an Identity Token. Treat it as a one-time, single-use pass that immediately expires 10 minutes after issuance.

​
Security Checklist

  1. Backend Only: Verification must ONLY happen on your secure backend server.
  2. Verify Issuer: Ensure the iss claim matches otpedge.com.
  3. Check Expiration: Verify the exp claim to ensure the token has not expired. Most JWT libraries (like jose or PyJWT) handle this automatically during verification.