Phone Sign-in

Phone sign-in lets people sign in with a 6-digit code sent to their phone, by text message, WhatsApp or a voice call. Someone without an account signs up the same way, then gives a name and an email. It runs on your hosted sign-in page, so there is nothing to change in your app.

Step by step, with screenshots: Set up phone sign-in.

Your provider, your bill

BuildBase has no messaging account of its own. Every code goes out through your provider: your own Twilio account, or a webhook of yours that hands the code to whichever provider you already use. Your provider bills you for each message. BuildBase never pays for, marks up or resells a message, and your plan carries no message quota.

Twilio Verify is the one to pick if you use Twilio: it covers all three channels, and Twilio makes and checks each code. WhatsApp through Twilio Messaging needs templates WhatsApp has approved in advance, so WhatsApp goes through Verify or the webhook.

Which countries can receive codes is your provider's setting, not ours. BuildBase accepts any valid phone number and does not filter by country or line type. With Twilio Verify, set the service's geo permissions to the countries you serve. Leaving every country open is how SMS pumping fraud, where a script requests codes to premium-rate numbers, turns into a bill.

Connecting a provider and adding the Phone method need a plan that includes phone sign-in codes. Without one, the console shows them locked.

Setting it up

1. Open User Management → Access → Authentication → SMS and choose how codes are sent.
   • Twilio: your account SID and auth token, and a Verify service SID (recommended), or a Messaging service SID or one of your Twilio numbers to send from. The credentials are checked with Twilio before they are saved, and a refusal shows Twilio's own message. The auth token is stored encrypted and is never shown again in full: the form shows a masked preview, and leaving the field blank keeps it.
   • Webhook: the HTTPS address of your endpoint. The first save makes a signing secret and shows it once, with a copy button. Put it in your endpoint's configuration before you send a test. Rotate secret makes a new one and shows it once; the old one stops working at once.
2. Set the daily cap and the share of it at which you are warned. See Limits.
3. Send a test to your own number from the same tab. It is a real message on your provider's bill and counts toward the cap. If your provider refuses it, the card shows why and the delivery log keeps the reason. A test that never reaches a provider says so instead: 429 daily_cap_reached once the day's cap is used up, and 409 sms_unavailable while no provider is connected.
4. Open the Methods tab, choose Add auth method, then Phone, and give it a title. Tick it on your client in the Settings tab. Until a provider is connected, the method is marked unavailable and no sign-in page offers it.
5. Back on the SMS tab, under Phone sign-in, choose the default country and the ways to send the code. The default country is where the picker on the sign-in page starts, and how a number typed without a country code is read. The ways to send are narrowed to what your provider can send; with more than one, people choose on the sign-in page.

Disconnect removes the provider. Phone codes stop at once: the sign-in page stops offering phone sign-in, and text messages stop working as a second step until a provider is connected again.

The signed webhook

For each code, BuildBase sends your endpoint a POST with a JSON body, waits up to 5 seconds, and does not retry. Someone is waiting on the sign-in page, and a code that arrives a minute later is no use to them.

{
  "to": "+14155550123",
  "code": "123456",
  "channel": "sms",
  "locale": "en",
  "purpose": "sign-in",
  "test": false
}

It is signed the way BuildBase's event webhooks are, with the secret from the SMS tab:

What your endpoint answers decides what happens next:

The SDK's verifyWebhookSignature checks the signature, in constant time, and refuses a request more than five minutes old, so a captured request cannot be replayed. Verify the raw body, before parsing it:

import { verifyWebhookSignature } from '@buildbase/sdk';

export async function POST(req: Request) {
  const body = await req.text();

  const valid = verifyWebhookSignature({
    body,
    signature: req.headers.get('x-buildbase-signature'),
    timestamp: req.headers.get('x-buildbase-timestamp'),
    secret: process.env.BUILDBASE_SMS_SECRET!,
  });
  if (!valid) return new Response('Invalid signature', { status: 401 });

  const { to, code, channel } = JSON.parse(body);
  const sent = await sendWithYourProvider({ to, channel, code });

  // A number your provider will not deliver to: say so, with a reason.
  if (!sent.ok) return Response.json({ reason: sent.reason }, { status: 422 });
  return Response.json({ sent: true });
}

Without the SDK, Node's crypto does the same:

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifySmsWebhook(
  rawBody: string,
  timestamp: string | undefined,
  signature: string | undefined,
  secret: string
): boolean {
  if (!timestamp || !signature) return false;
  // Refuse anything older than five minutes.
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected =
    'sha256=' +
    createHmac('sha256', secret)
      .update(`${timestamp}.${rawBody}`)
      .digest('hex');
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Webhook sends do not count toward your plan's webhook deliveries, and BuildBase never stores the code in a delivery record.

Limits

The per-number and per-address limits are counted before the number is looked up, so a number with an account and one without run out alike. These limits apply on every install, whatever its other rate-limit settings.

The four SMS_* names are environment variables on the tenant server of a self-hosted install. In the cloud, the daily cap is the one limit you set, in the console, from 1 to 100,000, and it counts test sends too. The day is the UTC day. Sent today on the SMS tab stops at the cap: past it, sends are refused rather than sent. When sends reach the warning share of the cap (80% unless you change it), BuildBase emits auth.sms_budget_exceeded with level: "warning", once that day. When the cap stops sends, it emits the same event with level: "stopped", once that day, and the sign-in page says codes cannot be sent right now.

The delivery log

The Delivery log on the SMS tab lists every send of the last 30 days, newest first: the last four digits of the number, the channel, what it was for, whether it was sent, refused or failed, and your provider's error code. The full number and the code are never kept. Rows older than 30 days are deleted.

Twilio's delivery status callbacks are not read, so the log records what your provider answered when the code was sent. A message Twilio accepted and then could not deliver shows as sent; Twilio's own message logs have the rest.

What people see

• Signing in. The person picks their country, types their number and, if you offer more than one, chooses text message, WhatsApp or a voice call. A number with no account gets exactly the same answer as one with an account, so the page cannot be used to find out who has an account.
• Each code is 6 digits, lasts 10 minutes and allows 5 tries. A new code can be sent after 30 seconds, and each new code replaces the last.
• Signing up. A number with no account is asked for a name and an email after the code. The email starts unverified: a verification code goes to it, as after any sign-up, and the person confirms it on the next screen. Phone sign-up therefore needs a connected email sender as well.
• An email that already has an account is never given the phone. The answer says the address cannot be used here, and suggests signing in to that account and adding the phone there. Linking the number there would hand the account to whoever holds the phone. An address your sign-up rules do not let in gets those rules' own answer instead, as on any other sign-up form.
• Closed sign-up. With public sign-up closed, a number with no account gets the answer a sent code gets, and no message is sent. Existing accounts still sign in by phone.
• The second step. If the org asks for one, a phone code is followed by it, as after any first step. A text message is never offered as the second step after a phone code.

A sign-in by phone code puts sms-otp in the user's activity, with the channel, and its token's amr claim says how: ["sms", "otp"] for a text message, ["otp"] for WhatsApp and ["tel", "otp"] for a voice call.

If you call the auth API yourself

The hosted page does this for you. The phone entry in GET /api/v1/auth/supported-methods carries the routes and the settings:

{
  "id": "phone",
  "type": "phone",
  "name": "Phone",
  "validScreens": ["login", "register"],
  "url": "https://api.console.buildbase.app/api/v1/auth/phone",
  "formDetails": { "defaultCountry": "US", "channels": ["sms", "whatsapp"] }
}

It is there when the client has the Phone method and a provider is connected. Numbers are always sent as E.164. Errors are { success: false, message, reason }; show message as it is.

POST <url>/send with phone, channel and, when bot protection is on, turnstileToken, answers { success: true, message, retryAfter: 30 }.

POST <url>/verify with phone and code answers a sign-in, { success: true, token }, or the second step's envelope, or, for a number with no account, { success: true, signupRequired: true, signupToken }. The sign-up token lasts 15 minutes.

POST <url>/register with signupToken, name, email and, when bot protection is on, turnstileToken, creates the account and answers like a sign-in.

A phone on a signed-in account

A signed-in person can add a number to their account, prove it with a code, and remove it, from your app's account settings. The routes are under /api/v1/public/profile, authorized by the session in the x-session-id header, and the profile carries phone and phoneVerified.

A verified number counts as a way in for connected accounts while your client offers phone sign-in.

Text messages as a second step

People can also get their two-step sign-in code by text message, if you allow it. It is the weaker choice: a phone number can be moved to another SIM by someone who talks a carrier into it, and a text can be intercepted. Offer it for people who would otherwise have no second step at all, not in place of the authenticator app.

• Allow it under User Management → Access → Authentication → Security, by ticking Text message codes in the two-step card. The list cannot be text messages alone; the authenticator app stays on beside it, and saving a list of text messages alone is refused with sms_only_factor.
• It needs a connected provider and a plan with phone sign-in codes. Without either, it is not offered.
• People turn it on from the Security screen of your app's settings, with a phone number they have verified.
• At sign-in, the hosted page offers "Text a code to" the masked number beside the authenticator app, as the weaker option, and sends nothing until asked. The code works once, and a new one can be sent after 30 seconds.
• Never after a phone code. A person who signed in with a code sent to their phone is not offered a text message as the second step.

Events

level is warning or stopped, each at most once a day. Subscribe to any of them as a webhook event.

Next steps

• Bot Protection - put a Turnstile check in front of code sends.
• Connected Accounts - the ways a person can sign in, and removing one.
• Importing Users - bring numbers over with an import.