​
Benefits of Using Prelude with Supabase

  • 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 Supabase’s phone authentication, allowing you to set up in minutes.

This guide walks you through the integration process step-by-step, so you can enhance your Supabase authentication system with Prelude’s powerful API.

​
Prerequisites

  • A Supabase project.
  • A Prelude account.

​
Step 1: Get Webhook URL

In Prelude’s dashboard, go to “Settings > Integrations > Supabase” to get the webhook URL and copy it.

​
Step 2: Add Webhook URL to Supabase

In your Supabase project dashboard, navigate to the “Authentication” section. Click on “Hooks” in the sidebar, then click the “Add a new hook” button. Select “Send SMS hook” from the options.

Once you click “Add a new hook”, you’ll land on a configuration page. First, turn on the “Send SMS hook” toggle - this tells Supabase to let Prelude handle all your phone authentication. You’ll need to pick “HTTPS” as the hook type (don’t worry about the other options, HTTPS is what we want here).

Next, grab that webhook URL you copied from Prelude earlier and paste it into the URL field. The last step is to click the “Generate secret” button to create a secure key - make sure to copy this key, you’ll need it in a minute! Click on “Create hook” to finish setting up the webhook.

​
Step 3: Add Secret from Supabase to Prelude

Head back to Prelude’s dashboard and navigate to “Settings > Integrations > Supabase”. You’ll see a field labeled “Secret” - paste the secret key you just generated in Supabase into this field and click “Add Secret”. This connects your Supabase project to Prelude securely.

Once added successfully, you’ll see the secret appear in the list below. You can add up to 3 secrets if needed, and revoke them at any time.

​
Step 4: Enable Phone Authentication on Supabase

In your Supabase project dashboard, navigate to the “Authentication” section. Click on “Providers” in the sidebar, then click the “Phone” provider. Turn on the “Enable Phone Provider” toggle and click “Save”.

​
You’re All Set!

Congratulations! You’ve successfully integrated Prelude with your Supabase project. Now when users authenticate using phone numbers in your Supabase application, Prelude will handle the SMS verification process seamlessly.

You can test this by implementing phone authentication in your application using Supabase’s client libraries. When a user attempts to sign in with their phone number, Supabase will automatically route the verification through Prelude’s service.

​
Troubleshooting

If you encounter any issues, here are some common error codes you may receive:

  • invalid_phone_number: The phone number provided is not in a valid E.164 format
  • invalid_api_key: The webhook secret is incorrect or missing
  • customer_not_found: The customer ID in the webhook URL is invalid
  • insufficient_balance: Your Prelude account needs to be topped up
  • blocked: The authentication attempt was blocked.

For a complete list of error codes and troubleshooting steps, see the Prelude API Reference.