Integrating Prelude with Auth0 for Secure and Reliable SMS Authentication

​

Benefits of Using Prelude with Auth0

• Improved SMS Deliverability – Prelude offers high success rates for message delivery, reducing the risk of authentication failures.
• Anti-Fraud Protection – Prelude’s advanced fraud detection system helps prevent abuse of your authentication system by identifying and blocking suspicious patterns.
• Multi-Region Routing – Prelude automatically routes messages through the optimal carrier network based on the destination country, ensuring fast delivery worldwide.
• Multi-Channel Support – Prelude supports SMS, WhatsApp, Viber and RCS channels for verification codes, giving your users more flexibility in how they receive authentication codes.
• Seamless Integration – Works effortlessly with Auth0’s phone authentication, allowing you to set up in minutes.

​

Prerequisites

• An Auth0 project.
• A Prelude account.

​

Step 1: Configure Prelude for Auth0

• Create a new Secret Key for your Auth0 integration on Settings > API Keys and don’t forget to save or copy it.
• Enable the Auth0 integration by going to Settings > Integrations > Auth0 in your Prelude’s Dashboard.
• Create a new Webhook Key for your Auth0 integration and don’t forget to save or copy it.

​

Step 2: Add a custom phone provider with the Auth0 Dashboard

1. Open the Auth0 Dashboard and go to Branding > Phone Provider.
2. On the Phone Message Provider page, you’ll notice Twilio is selected by default.
3. In the Phone Provider section, select the Custom option.
4. Under Delivery Method, choose Text and Voice. Both are supported by Prelude, but Voice should be explicitly enabled from Prelude dashboard.
5. In the Provider Configuration area:
   • Click the key icon to add a secret. Name it PRELUDE_SECRET_KEY and paste your Prelude API Key.
   • Click the box icon to add dependencies:
     • Add @prelude.so/sdk (leave the version field empty).
     • Add ua-parser-js (leave the version field empty).
6. Paste the following code into the editor. This code will send verification requests to Prelude and enrich them with device and context signals for better security and deliverability.

const parser = require("ua-parser-js");
const Prelude = require("@prelude.so/sdk");

function categorizeDevice(data) {
  const osName = (data.os.name || "").toLowerCase();
  const deviceModel = (data.device.model || "").toLowerCase();
  const deviceType = (data.device.type || "").toLowerCase();

  if (deviceModel === "ipad") return "ipados";
  if (deviceModel === "macintosh") return "web";
  if (deviceModel === "iphone") return "ios";
  if (deviceType === "smarttv") return "tvos";
  if (osName.includes("android")) return "android";
  if (!deviceType && !data.device.model && !data.device.vendor) return "web";

  return undefined;
}

function getDeviceModel(ua) {
  if (!ua.device || (!ua.device.vendor && !ua.device.model)) {
    return undefined;
  }

  const { vendor, model } = ua.device;

  if (vendor) {
    return `${vendor}/${model || ""}`.trim();
  }

  return model || undefined;
}

exports.onExecuteCustomPhoneProvider = async (event, api) => {
  const client = new Prelude({
    apiToken: event.secrets.PRELUDE_SECRET_KEY,
  });

  const { recipient, code, delivery_method } = event.notification;
  const { ip, language } = event.request;

  const ua = parser(event.request.user_agent);

  const correlationId = `auth0:${event.tenant.id}:${event.user.user_id}`;

  const method = delivery_method === "voice" ? "voice" : "auto";

  await client.verification.create({
    target: {
      type: "phone_number",
      value: recipient.replace(/[\s-]/g, ""),
    },
    metadata: {
      correlation_id: correlationId,
    },
    signals: {
      ip,
      os_version: ua.os.version,
      device_model: getDeviceModel(ua),
      device_platform: categorizeDevice(ua),
    },
    options: {
      locale: language,
      custom_code: code,
      method,
      integration: "auth0", // important
    },
  });
};

7. Click the Save button at the bottom of the page to apply your configuration.
8. (Optional) If you created your Auth0 tenant before September 2025, you may need to enable Use Tenant-Level Messaging Provider in Security > Multi-factor Auth (MFA) > Phone number.

​

Step 3: Set Up the Verification Webhook

1. In the Auth0 dashboard, navigate to Monitoring > Log Streams.
2. Click Create Log Stream.
3. Choose Custom Webhook as the stream type.
4. Name your log stream (e.g., Prelude Check) to easily identify it later.
5. Fill in the configuration fields as follows:

6. Click Save to apply your webhook configuration.

Note: It’s important to leave the “phone” field unobscured so Prelude can properly process and verify phone number authentications. All other sensitive fields can remain obscured for privacy.

• Enable MFA
• SMS-based Passwordless Authentication

​

Correlation ID

auth0:${event.tenant.id}:${event.user.user_id}

​

You’re All Set!