Changing a customer's phone number safely: confirm the new number before saving it

Security·· 99 views· 3 min read

The short answer: when a customer changes the mobile number on their account, send a code to the new number and only save it after valid: true. Before that, make sure it really is the account owner asking: whoever can swap someone else's number starts receiving their codes, and with them their logins and payments.

Why this moment is sensitive

If the phone is the second login step, or the channel for payment codes, the number is a key. A session left open on a shared computer, or a stolen password, is all someone needs to try putting their own number there. So the change needs two confirmations: from the person asking, and from the new number.

The change, step by step

1 Confirm who is asking. Ask for the password again, or send a code to the old number with POST /v1/sms/otp. If the customer no longer has the old number, pass the case to your team, with an identity check.
2 Ask for the new number and send it a code, with a text that says what it is for: [COMPANY]: code {code} to confirm this number on your account..
3 Store the new number as “unconfirmed”, together with the code's id. The old number stays in use until the end.
4 Check it with /verify. With valid: true, switch the number and save the time (verified_at).
5 Tell the old number with a normal SMS through the SMS API: “The number on your account was changed. If this was not you, contact us on [PHONE].”
6 If the customer gives up halfway, cancel the pending code with POST /v1/sms/otp/{id}/cancel and delete the “unconfirmed” number.

What not to do

Mistake What happens
Saving the new number at once, before the code One wrong digit leaves the customer without codes, and an attacker gets them instead.
Changing the number with only an open session Whoever finds the open session takes over the account.
Not telling the old number The real owner only finds out when they can no longer sign in.
Using a code sent to the old number to confirm the new one It proves the customer has the old phone, not that the new one is theirs.
A new code for the same number cancels the previous one. If your system sends two codes in a row to the new number (after a double click, say), only the last one works. Use the Idempotency-Key header when sending, so a double click returns the same response and no second SMS.
The same care applies to the account e-mail and any other detail used to recover access. The rule is the same: confirm who is asking, confirm the new detail, tell the old one. For two-step login, see login with an SMS code.

Want to confirm new numbers before saving them? See Verification SMS.

See Verification SMS

SEE ALSO

Two-step login with an SMS code on your own site or app

Confirming a phone number at sign-up with an SMS code, step by step

Code-sharing scams: protecting your customers from people who ask for their SMS code

SMS verification API: we generate, send and check the code, and your system keeps only the id

Resending, cancelling and replacing a verification code: what happens to the old one

Sending one-time codes (OTP) by SMS safely: expiry, attempt limits and logs

RECOMMENDED PRODUCT

Web hosting with cPanel

Domain and SSL included, daily backups and the panel you already know. from $6.60/mo (3-year plan, with coupon)

See plans
Was this answer helpful? Your answer helps us improve this article.

Related Articles

Security 2,328 What is an SSL certificate and why does it matter? An SSL certificate encrypts the connection between a visitor's browser and your site, so passwords, card numbers and any...
Security 2,371 Why does my SSL certificate show fewer than 365 days? If you're on the free SSL every account gets by default, this doesn't apply to you - skip to the note below. This is onl...
Security 3,979 How to redirect HTTP to HTTPS with .htaccess This forces every visitor to the encrypted version of your site, even if they type or link to the plain http:// address....
Security 2,257 How to tell if your site has been compromised Most infections don't announce themselves - they show up as small, odd symptoms before anything looks obviously wrong. S...
Security 2,139 How to clean up a compromised site Cleaning up is only half the job - if the door that let the infection in stays open, it comes back. Work through this in...
Security 72 Limits against abuse: codes per number per hour and the wait between resends The short answer: your account has two rules for verification codes, and by default both are off (value 0): resend_wait_...