🟪 RAuth Provider (v2)

A production-ready Node.js backend SDK for the RAuth v2 authentication platform — enabling OTP-free, secure, and real-time user verification.

🚀 Overview

RAuth Provider helps backend developers integrate Reverse Authentication (via WhatsApp, Reverse SMS, or the OneID App) and passkey-based verification without building complex verification flows.

It also provides session and approval token management for handling both authentication and authorization with high security.

✅ Features

• 📲 Reverse Authentication – Verify users through WhatsApp, Reverse SMS, or OneID (no OTPs)
• 🔐 Session Management – Create, validate, and auto-revoke active sessions
• 📡 Real-Time Updates – Instantly sync token status using built-in SSE
• 🧩 Plug-and-Play API – Simple, developer-friendly API surface
• ⚡ Express Middleware Support – Drop-in integration for Express.js
• 🛡️ Secure by Design – Uses JWT validation and authenticated API calls
• 🧠 Smart Caching – In-memory tracking with API fallback for resilience
• 🔗 Fully Compatible with RAuth APIs – Directly integrates with the api.rauth.io/v2/ backend
• 💜 TypeScript Native – Complete type definitions for modern development

📦 Installation

npm install rauth-provider

⚙️ Quick Start (Hybrid ESM + CommonJS)

ESM / TypeScript (Recommended)

import { RauthProvider } from 'rauth-provider';

RauthProvider.init({
  api_key: process.env.RAUTH_API_KEY!,
  app_id: process.env.RAUTH_APP_ID!,
});

// Verify a session (phone must match and status must be verified)
const sessionOk = await RauthProvider.verifySession('session-token', '+1234567890');

// Verify an approval (approval_token must map to a verified session for the phone)
const approval = await RauthProvider.verifyApproval('approval-token', '+1234567890');

CommonJS (Legacy Node.js)

const { RauthProvider } = require('rauth-provider');

RauthProvider.init({
  api_key: process.env.RAUTH_API_KEY,
  app_id: process.env.RAUTH_APP_ID,
});

const sessionOk = await RauthProvider.verifySession('session-token', '+1234567890');
const approval = await RauthProvider.verifyApproval('approval-token', '+1234567890');

ℹ️ Note: RauthProvider is a singleton instance — once initialized, it maintains shared state across your entire backend.

🧰 Usage Examples

ESM / TypeScript (Express + JWT + Approval Token)

The following examples demonstrate how to integrate RAuth with Express.js for login, sensitive actions, and secure routes.

import express from 'express';
import jwt from 'jsonwebtoken';
import { RauthProvider } from 'rauth-provider';

const app = express();
app.use(express.json());

RauthProvider.init({
  api_key: process.env.RAUTH_API_KEY!,
  app_id: process.env.RAUTH_APP_ID!,
});

// 1) Login: exchange a verified session for your own JWT
app.post('/auth/login', async (req, res) => {
  const { session_token, phone } = req.body;
  const ok = await RauthProvider.verifySession(session_token, phone);
  if (!ok) return res.status(401).json({ error: 'not_verified' });

  const jwtToken = jwt.sign({ phone, session_token }, process.env.JWT_SECRET!, {
    expiresIn: '24h',
  });
  return res.json({ token: jwtToken });
});

// 2) Sensitive action: verify approval token
app.post('/actions/transfer', async (req, res) => {
  const { approval_token, phone, amount } = req.body;
  const result = await RauthProvider.verifyApproval(approval_token, phone);
  if (!result.valid) return res.status(401).json({ error: 'approval_invalid' });

  // Continue with action (e.g., transfer money)
  return res.json({ success: true, action: result.action, amount });
});

// 3) Protected route example (check revocation)
app.get('/secure', async (req, res) => {
  try {
    const token = req.headers.authorization?.replace('Bearer ', '') || '';
    const decoded = jwt.verify(token, process.env.JWT_SECRET!);
    const revoked = await RauthProvider.isSessionRevoked(decoded.session_token, decoded.phone);
    if (revoked) return res.status(401).json({ error: 'session_revoked' });
    return res.json({ ok: true, user: decoded.phone });
  } catch (e) {
    return res.status(401).json({ error: 'invalid_jwt' });
  }
});

app.listen(3000, () => console.log('Server running on 3000'));

CommonJS (Express + JWT + Approval Token)

const express = require('express');
const jwt = require('jsonwebtoken');
const { RauthProvider } = require('rauth-provider');

const app = express();
app.use(express.json());

RauthProvider.init({ api_key: process.env.RAUTH_API_KEY, app_id: process.env.RAUTH_APP_ID });

app.post('/auth/login', async (req, res) => {
  const { session_token, phone } = req.body;
  const ok = await RauthProvider.verifySession(session_token, phone);
  if (!ok) return res.status(401).json({ error: 'not_verified' });
  const token = jwt.sign({ phone, session_token }, process.env.JWT_SECRET, { expiresIn: '24h' });
  res.json({ token });
});

app.post('/actions/transfer', async (req, res) => {
  const { approval_token, phone, amount } = req.body;
  const result = await RauthProvider.verifyApproval(approval_token, phone);
  if (!result.valid) return res.status(401).json({ error: 'approval_invalid' });
  res.json({ success: true, action: result.action, amount });
});

📘 API Reference

RauthProvider.init(options)

Initializes the RAuth Provider with your credentials and optional configuration.

Parameters:

• api_key (string, required): Your RAuth API key
• app_id (string, required): Your RAuth App ID
• logs (boolean, optional): Enable console logging for debugging (default: false)

RauthProvider.init({
  api_key: process.env.RAUTH_API_KEY!,
  app_id: process.env.RAUTH_APP_ID!,
  logs: true, // Enable logging for development
});

ℹ️ Tip: Set logs: true during development to see SSE events and internal state changes. Disable in production for cleaner logs.

RauthProvider.verifySession(sessionToken, userPhone)

Verifies that a session is valid, matches the given phone number, and is marked as verified.

const isValid = await RauthProvider.verifySession('session-token', '+1234567890');
// Returns: Promise<boolean>

RauthProvider.isVerified(sessionToken, userPhone)

Alias for verifySession() that returns a boolean.

const isVerified = await RauthProvider.isVerified('session-token', '+1234567890');

RauthProvider.isSessionRevoked(sessionToken, userPhone)

Checks if a given session token has been revoked.

const isRevoked = await RauthProvider.isSessionRevoked('session-token', '+1234567890');
// Returns: Promise<boolean>

RauthProvider.checkApiHealth()

Tests connectivity with the RAuth API.

const isHealthy = await RauthProvider.checkApiHealth();
// Returns: Promise<boolean>

🧩 Additional helpers:

• getSessionStatus(sessionToken, phone)
• verifyApproval(approvalToken, phone)

🔑 Token Types Explained

1️⃣ Session Token (Authentication)

Purpose: Used during user signup or login to verify their mobile number and establish an authenticated session.

Lifecycle: Generated via /v2/session/init, becomes verified after the user confirms through WhatsApp, Reverse SMS, or OneID. It’s then exchanged for your app’s own JWT or session.

Validation: Backend verifies { session_token, phone } using /v2/backend/session/status or the SDK helper verifySession().

Example (Login Flow):

// Exchange a verified session for your own JWT
app.post('/auth/login', async (req, res) => {
  const { session_token, phone } = req.body;
  const ok = await RauthProvider.verifySession(session_token, phone);
  if (!ok) return res.status(401).json({ error: 'not_verified' });

  const token = jwt.sign({ phone, session_token }, process.env.JWT_SECRET!, { expiresIn: '24h' });
  return res.json({ token });
});

When to use:

• User signup/login
• Device or browser re-verification
• Session restoration after inactivity

2️⃣ Approval Token (Authorization / Step-Up Authentication)

Purpose: Authorizes high-risk or sensitive actions (e.g., payments, password reset) after login. Works seamlessly with Passkeys and OneID for biometric or in-app confirmation.

Lifecycle: Short-lived and one-time use, bound to an existing verified session. Generated when the frontend requests approval from the user, then verified by the backend before executing an action.

Validation: Backend verifies { approval_token, phone } using /v2/approval/verify or the SDK helper verifyApproval().

Example (Sensitive Action):

// Verify approval token before executing a sensitive operation
app.post('/payments/transfer', async (req, res) => {
  const { approval_token, phone, amount, recipient } = req.body;
  const result = await RauthProvider.verifyApproval(approval_token, phone);
  if (!result.valid) return res.status(401).json({ error: 'approval_invalid' });

  // Proceed with transfer
  return res.json({ success: true, amount, recipient });
});

Passkey & OneID Integration:

• Passkeys enable biometric 2FA (e.g., FaceID, fingerprint)
• OneID app can prompt users for instant approval; SDK receives these via SSE events

When to use:

• Financial transactions
• Password or 2FA changes
• KYC submissions or data updates
• Compliance-driven re-authentication

⚙️ Environment Variables

Create a .env file in your root directory:

RAUTH_API_KEY=your-rauth-api-key
RAUTH_APP_ID=your-app-id
JWT_SECRET=your-jwt-secret

❗ Error Handling

The SDK throws detailed and structured errors. Wrap all calls in try/catch for robust handling.

try {
  RauthProvider.init({});
} catch (error) {
  console.error(error.message);
  // Example: "RauthProvider.init(): Missing required fields: api_key, app_id"
}

API errors include HTTP context (e.g., RAuth API error 400: Invalid token).

🧩 Compatibility

| Environment | Supported | Notes | | -------------------- | ------------------------ | ----------------------------------------------------- | | ESM / TypeScript | ✅ | import { RauthProvider } from 'rauth-provider' | | CommonJS | ✅ | const { RauthProvider } = require('rauth-provider') | | Frameworks | Express, NestJS, Fastify | Works out of the box | | Node.js | ≥ 16.x | Required for ESM compatibility |

🧠 Summary

| Token Type | Purpose | Lifespan | Example Use | | ------------------ | ---------------------------------- | -------------------- | ------------- | | Session Token | Mobile verification & login | Long (session-bound) | Signup/Login | | Approval Token | Step-up auth for sensitive actions | Short (one-time use) | Payments, 2FA |

RAuth Provider (v2) — making passwordless, OTP-free authentication effortless for developers.

💡 Designed for simplicity. Secured by cryptography. Powered by RAuth.io.