Sign in with iMessage

Your user taps a button, Messages opens with SIGNIN and a short code addressed to your number, and they tap Send. We post the text to your webhook, your auth provider issues the session, and the user is signed in without typing a code.

Pro is $49/month per number. Limits apply.

Acme Notes

Sign in to your notes

  1. Code createdSIGNIN 4F7K2Q, valid for 10 minutes
  2. Text receivedmessage.received, with the sender’s handle
  3. Session issuedYour auth provider signs the user in
Acme Notes
Today 8:14 AM
SIGNIN 4F7K2Q

Tap to open Messages. Scan to sign in from a laptop.

On a compatible Apple device with Messages, a button opens Messages. Anywhere else the page shows a QR code, and the browser tab signs in once they send.

Your sign-in page on an Apple device

Opens Messages addressed to your number, with SIGNIN 4F7K2Q already typed. The user taps Send, then swipes back to the app.

Scan with an iMessage-capable device, then tap Send.

Or text SIGNIN 9QX2LM to +1 805 555 0100.

Waiting for the text

Sending an iMessage takes an Apple device, so Android users get your existing sign-in. Keep it beside Sign in with iMessage.

Your auth provider issues the session.

We carry the text. Your backend matches the code, finds or creates the user by handle, and mints a session with the provider you already use.

python
async def mint_session(handle: str) -> dict:
    try:
        user = auth.get_user_by_phone_number(handle)
    except auth.UserNotFoundError:
        user = auth.create_user(phone_number=handle)
    token = auth.create_custom_token(
        user.uid, {"imessage_verified": True})
    return {"provider": "firebase",
            "custom_token": token.decode()}

The app calls signInWithCustomToken with it, and the token expires after one hour. An E.164 handle is shown here. An email handle uses the email calls.

python
async def mint_session(handle: str) -> dict:
    held_otps[handle] = asyncio.get_running_loop().create_future()
    # Supabase calls your Send SMS hook with the code.
    # You hold it and never send it.
    await http.post(f"{SUPABASE_URL}/auth/v1/otp",
        headers={"apikey": ANON_KEY},
        json={"phone": handle, "create_user": True})
    otp = await asyncio.wait_for(held_otps.pop(handle), 10)
    return {"provider": "supabase", "phone": handle, "otp": otp}

The app finishes with verifyOTP. Supabase phone auth needs an E.164 number.

python
async def mint_session(handle: str) -> dict:
    held_codes[handle] = asyncio.get_running_loop().create_future()
    await http.post(f"{AUTH0}/passwordless/start", json={
        "client_id": CLIENT_ID, "client_secret": CLIENT_SECRET,
        "connection": "sms", "phone_number": handle,
        "send": "code"})
    # your Send Phone Message Action hands the code back
    code = await asyncio.wait_for(held_codes.pop(handle), 10)
    return {"provider": "auth0", "phone": handle, "code": code}

The app logs in with the phone number and the held code.

python
async def mint_session(handle: str) -> dict:
    users = (await c.get(f"{CLERK}/users",
             params={"phone_number": [handle]})).json()
    uid = users[0]["id"] if users else (await c.post(
        f"{CLERK}/users", json={"phone_number": [handle],
        "skip_legal_checks": True})).json()["id"]
    tok = (await c.post(f"{CLERK}/sign_in_tokens", json={
        "user_id": uid, "expires_in_seconds": 300})).json()
    return {"provider": "clerk", "ticket": tok["token"]}

The app redeems the ticket with Clerk’s ticket strategy.

python
async def mint_session(handle: str) -> dict:
    user = db.get_or_create_user(handle=handle)
    return {"provider": "own", "session": issue_session(user)}

Store the handle exactly as returned and issue your own cookie or JWT. The contract is the same for every provider: once the handle is proven, you issue whatever your app already accepts.

0new contacts used

Sign-ins never use a new contact.

300 sign-ins on one Pro number in a day add 300 inbound texts and no new contacts. All 5 of the number’s new contacts for the day stay free.

How Sign in with iMessage works

It reverses the one-time-code direction. The user texts a code to your number, and the signed webhook tells your backend which handle sent it.

  1. StartYour backend creates an attempt with a single-use code. In the docs’ reference implementation it is 6 characters from a 32-character alphabet, valid for 10 minutes.
  2. SendThe app opens sms:+18055550100&body=SIGNIN%204F7K2Q. Messages opens to your number with the text prefilled, and the user taps Send.
  3. ReceiveWe POST a signed message.received event with the handle and text to your webhook, about 1 to 2 seconds after the line receives it.
  4. Match and mintYour backend checks that the message arrived over iMessage, matches the code, marks the attempt verified with that handle, mints a session, and puts a thumbs-up tapback on the text with POST /api/imessage/reactions.
  5. Sign inThe app polls the attempt every 2 seconds and receives the session, once, when it is verified.
bash
# register your webhook once; the secret in the response is shown once
curl -s -X PUT \
  -H "Authorization: Bearer $ZEROSETTLE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://auth.example.com/webhook"}' \
  https://portal.zerosettle.io/api/imessage/webhook

# the tapback your backend sends once the code matches
curl -s -X POST \
  -H "Authorization: Bearer $ZEROSETTLE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"message_id": 4821, "reaction": "like"}' \
  https://portal.zerosettle.io/api/imessage/reactions

The reference implementation is one backend you run, with three routes (start, webhook, status) and a provider-specific mint_session. The Sign in with iMessage docs have the Swift and browser code. How webhooks work covers signing and retries.

What a sign-in proves

It verifies possession of an iMessage handle, the same guarantee as an SMS code. Your auth provider still issues the session.

The handle

The handle in the webhook is what Apple attached to the message: an E.164 number for almost everyone, or an email address for iMessage-only devices. Store it exactly as returned, as the user’s verified identifier, and show the user which number they signed in with.

The code

Codes are random, single-use and expire in 10 minutes. Match them with a strict regex on the whole word and ignore every other inbound message. The attempt id is the secret and the code is not, so return the session only to the caller holding the id, once.

Checks on your side

Verify the webhook signature on the raw body and dedupe on the message id, because retries are real. Rate-limit your /start route per IP and per device. Log sign-ins with the message id as your audit trail.

Not phishing-resistant

NIST SP 800-63B says out-of-band authentication is not phishing-resistant. A user tricked into texting someone else’s code signs that person in to the user’s account. Use it where an SMS code would do.

What a sign-in counts against

Sign-ins use none of the new-contact allowance. Each number handles up to 10,000 messages a day, sent and received, with known contacts.

Part of the sign-inCounted asLimit
The user’s SIGNIN textInbound message10,000 a day per number, sent and received
Your thumbs-up tapbackA reaction, never a new contactNone
A later text to that userAn ongoing conversation, because they texted firstNo new-contact limit; 2 unanswered messages per contact on every plan
Calls to your /start routeYour server, not oursYours to set

Signing in is not marketing consent

The user texts to prove a handle, not to hear offers. Our docs advise asking separately before sending anything promotional, and sending it only between 8 am and 9 pm in their time zone. Consent rules vary by country and use. This is not legal advice, so check with counsel.

STOP

A user who texted STOP earlier can still sign in, because they are the one texting. The confirming tapback to them is blocked with 403 recipient_opted_out, so do not depend on it. See how STOP works.

Not a fit

Most of your users are on Android. You need phishing-resistant sign-in, such as hardware security keys. Users sign in on a desktop with no device that can send an iMessage nearby, because the QR flow needs an Apple device with iMessage to send from. You cannot run a webhook or a poller to match codes.

A flat price per number

No per-message or per-code fee, and a 30-day money-back guarantee on Pro. Sign-ins use no credits.

Pro

For sign-ins and everything customers text first

$49 /mo per number

  • 5 new contacts a day per number
  • Sign-ins never count against it
  • No per-message or per-code fee
  • 30-day money-back guarantee
Get started

Questions

Is Sign in with iMessage more secure than SMS codes?

About the same. It proves possession of the handle, as an SMS code does, and adds the handle Apple attached to the message, which our docs call a stronger identifier than a number the user typed. Neither is phishing-resistant under NIST SP 800-63B.

Can users sign in from an iPad or a Mac?

Yes. On an iPad, or a Mac with Messages, the button opens Messages directly. From an iMessage-only device the handle can be an email address, which Firebase, Clerk and your own auth accept but Supabase phone auth does not. That email is a different handle from the user’s number, so link the two to one account rather than letting mint_session create a second.

What about users who already have an account, such as through Sign in with Apple?

Attach the verified handle to the existing account instead of creating a second one. Most providers have a link or update-user call. In Firebase, auth.update_user sets phone_number on the existing record.

Do I need a webhook for Sign in with iMessage?

No. You can poll GET /api/imessage/messages?after_id=… instead, and inbound messages appear there within about 1 to 2 seconds. Our docs prefer the webhook because it is pushed and signed.

Does a sign-in use a new contact?

No. The user texts your line first, so a sign-in is an inbound message and never counts against the new-contact limit. Our tapback back to them is a reaction, which never counts as a new contact either.

Does it work for Android users?

The sign-in flow requires a message sent over iMessage. For Android users, offer your existing sign-in method. SMS fallback applies to eligible one-to-one plain texts.

Start with one number

Get a number and sign in to your own app with a text.