Skip to content
Branch: master
Find file History
hober Add note on extensibility. Fixes #20. (#21)
* Add note on extensibility. Fixes #20.

* Add @a2sheppy to acks.

* re-ran doctoc
Latest commit 34853bf Feb 4, 2020
Type Name Latest commit message Commit time
Failed to load latest commit information.
Makefile Add Makefiles for easier explainer updating. Feb 1, 2020 Add note on extensibility. Fixes #20. (#21) Feb 4, 2020

Delivering origin-bound one-time codes over SMS



Table of Contents


Many websites make use of one-time codes for authentication.

SMS is a popular mechanism for delivering such codes to users, but using SMS to deliver one-time codes can be risky.

This proposal attempts to reduce some of the risks associated with SMS delivery of one-time codes. It does not attempt to reduce or solve all of them. For instance, it doesn't solve the SMS delivery hijacking risk, but it does attempt to reduce the phishing risk.

Deficiencies of the status quo

Suppose a user receives the message "747723 is your FooBar authentication code." It's possible, even likely, that 747723 is a one-time code for use on But because there is no standard text format for SMS delivery of one-time codes, systems which want to make programmatic use of such codes must rely on heuristics, both to locate the code in the message and to associate the code with a website. Heuristics are prone to failure and may even be hazardous.


The goals of this proposal are:

  1. To eliminate the need to rely on heuristics for extraction of one-time codes from SMS. (Ideally, end users shouldn't have to manually copy-and-paste one-time codes from SMSes to their browser.)
  2. To reliably associate one-time codes intended for use on a specific website with that site. (One-time codes sent by a website should ideally only be entered on the actual site which sent it.)


We must not expose the contents of SMS messages to websites.


To address this, we propose a lightweight text format that services may adopt for such messages. It's about as simple as it gets. It begins with (optional) human-readable text. After the human-readable text both the code and the origin appear on a single line, with sigils denoting which is which. This is the last line of the text. Here's an example:

747723 is your FooBar authentication code. #747723

In this example, "747723 is your FooBar authentication code." is the human-readable explanatory text, "" identifies the origin ( for which the code is to be used, and "#747723" identifies the one-time code (747723). "@" and "#" are sigils used to identify the text that follows them. Any origin which is schemelessly same site as is an origin on which this code may be used.

Adoption of this format would improve the reliability of systems which today heuristically extract one-time codes from SMS, with clear end-user benefit. It improves reliability of both extracting the code and also associating that code with an origin.

Adoption of this proposal could improve the number of services on which a browser can offer assistance with providing SMS one-time codes to websites (e.g. an AutoFill feature), and could reduce the odds users would enter one-time codes delivered over SMS on sites other than the originating one.


If in the future we identify additional information to include in the payload, new syntax may be introduced after the one-time code in the last line. (N.B. future spec editor: the parser must ignore unrecognized trailing content on that line, to enable this.)

Alternative approaches

No special syntax (status quo)

We believe the status quo provides insufficient programmability (because it relies on heuristics) and, in particular, many typical SMS one-time code message formats in the wild lack reliable origin information.

Stakeholder Feedback

  • Apple / Safari / WebKit: Positive (shipped an earlier version in iOS 12 / Safari 12 for macOS)
  • Google / Chrome / Blink: Positive (Sam Goto and Steven Soneff gave a lot of feedback early in this work.)
  • Firefox / Gecko : Unknown


Many thanks to Aaron Parecki, Eric Shepherd, Eryn Wells, Jay Mulani, Paul Knight, Ricky Mondello, Sam Goto, and Steven Soneff for their valuable insights.

You can’t perform that action at this time.