OpportunitiesEntities
Docs
    Ring Platform

    Decentralized Self-building Future

    Sign In
    Entities
    Opportunities
    Store
    Docs
    Platform Concepts
    RING EconomySonoratek LLCGlobal ImpactAI Meets Web3
    Get Started
    Quick StartCalculatorRoadmap
    Privacy|Contact
    v1.106.29|Sonoratek LLC

    Documentation

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Features
    Multi-Vendor Store
    Inventory & Stock
    Vendor Management
    Commissions & Settlements
    Membership & Credits
    SubscriptionConductor
    PaymentConductor
    Ring Oracle
    Payments Overview
    Public Pools & DAO Jars
    WayForPay Payment Integration
    Wallet & Credit System
    WalletConductor
    Credit Rewards
    Affiliate & Referral Enablement
    Referral Codes (Refcodes)
    Page Curtain
    NFT Exhibition Marketplace
    Solana NFT Gates
    Token Staking System
    Owner Project Lab
    Entities
    Opportunities
    Real-Time Messaging
    Ring Tasks
    WebRTC Calls & STUNner TURN
    Peer Games
    News Module
    Member Blogs
    Public Profile Pages
    Profile Account Widgets
    Ring File Cabinet
    Username Reservation System
    Scientific Editor
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Email AI-CRM
    Ring Mailer & RingdomX Mail
    Tunnel Protocol
    VideoConductor
    MediaConductor
    Generative Gallery
    Authentication
    Phone OTP sign-in
    Security & Compliance
    Admin console
    Admin Wiki
    Manage via Telegram
    Locale System
    Mobile Experience
    Performance Optimization Patterns
    Examples
    Quick Start
    Basic Setup
    White Label
    Custom Branding
    Web3 Integration
    Real World
    Advanced Features
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Vertical Presets (SSOT)
    Ringization playbook
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Project configuration
    Public environment variables
    Order Lab secrets
    WalletConnect Project ID (Reown Cloud)
    Supported services
    NODUS wiki (project knowledge)
    Configuration playbook
    Web3
    Token launch jurisdictions
    Wallet
    Wallet Security Tips
    Integrations
    Ethereum wallets (Wagmi v3)
    RingFileBase (object storage API)
    Ring CDN (RingFileBase edge)
    Deployment
    Self-hosted deployment
    Vercel Deployment
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    News Kingdom architecture
    Backend Services
    Firebase Integration
    Development
    Ring MCP Server
    OSS vs enterprise

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)

    Documentation

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Features
    Multi-Vendor Store
    Inventory & Stock
    Vendor Management
    Commissions & Settlements
    Membership & Credits
    SubscriptionConductor
    PaymentConductor
    Ring Oracle
    Payments Overview
    Public Pools & DAO Jars
    WayForPay Payment Integration
    Wallet & Credit System
    WalletConductor
    Credit Rewards
    Affiliate & Referral Enablement
    Referral Codes (Refcodes)
    Page Curtain
    NFT Exhibition Marketplace
    Solana NFT Gates
    Token Staking System
    Owner Project Lab
    Entities
    Opportunities
    Real-Time Messaging
    Ring Tasks
    WebRTC Calls & STUNner TURN
    Peer Games
    News Module
    Member Blogs
    Public Profile Pages
    Profile Account Widgets
    Ring File Cabinet
    Username Reservation System
    Scientific Editor
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Email AI-CRM
    Ring Mailer & RingdomX Mail
    Tunnel Protocol
    VideoConductor
    MediaConductor
    Generative Gallery
    Authentication
    Phone OTP sign-in
    Security & Compliance
    Admin console
    Admin Wiki
    Manage via Telegram
    Locale System
    Mobile Experience
    Performance Optimization Patterns
    Examples
    Quick Start
    Basic Setup
    White Label
    Custom Branding
    Web3 Integration
    Real World
    Advanced Features
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Vertical Presets (SSOT)
    Ringization playbook
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Project configuration
    Public environment variables
    Order Lab secrets
    WalletConnect Project ID (Reown Cloud)
    Supported services
    NODUS wiki (project knowledge)
    Configuration playbook
    Web3
    Token launch jurisdictions
    Wallet
    Wallet Security Tips
    Integrations
    Ethereum wallets (Wagmi v3)
    RingFileBase (object storage API)
    Ring CDN (RingFileBase edge)
    Deployment
    Self-hosted deployment
    Vercel Deployment
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    News Kingdom architecture
    Backend Services
    Firebase Integration
    Development
    Ring MCP Server
    OSS vs enterprise

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)

    Documentation

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Features
    Multi-Vendor Store
    Inventory & Stock
    Vendor Management
    Commissions & Settlements
    Membership & Credits
    SubscriptionConductor
    PaymentConductor
    Ring Oracle
    Payments Overview
    Public Pools & DAO Jars
    WayForPay Payment Integration
    Wallet & Credit System
    WalletConductor
    Credit Rewards
    Affiliate & Referral Enablement
    Referral Codes (Refcodes)
    Page Curtain
    NFT Exhibition Marketplace
    Solana NFT Gates
    Token Staking System
    Owner Project Lab
    Entities
    Opportunities
    Real-Time Messaging
    Ring Tasks
    WebRTC Calls & STUNner TURN
    Peer Games
    News Module
    Member Blogs
    Public Profile Pages
    Profile Account Widgets
    Ring File Cabinet
    Username Reservation System
    Scientific Editor
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Email AI-CRM
    Ring Mailer & RingdomX Mail
    Tunnel Protocol
    VideoConductor
    MediaConductor
    Generative Gallery
    Authentication
    Phone OTP sign-in
    Security & Compliance
    Admin console
    Admin Wiki
    Manage via Telegram
    Locale System
    Mobile Experience
    Performance Optimization Patterns
    Examples
    Quick Start
    Basic Setup
    White Label
    Custom Branding
    Web3 Integration
    Real World
    Advanced Features
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Vertical Presets (SSOT)
    Ringization playbook
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Project configuration
    Public environment variables
    Order Lab secrets
    WalletConnect Project ID (Reown Cloud)
    Supported services
    NODUS wiki (project knowledge)
    Configuration playbook
    Web3
    Token launch jurisdictions
    Wallet
    Wallet Security Tips
    Integrations
    Ethereum wallets (Wagmi v3)
    RingFileBase (object storage API)
    Ring CDN (RingFileBase edge)
    Deployment
    Self-hosted deployment
    Vercel Deployment
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    News Kingdom architecture
    Backend Services
    Firebase Integration
    Development
    Ring MCP Server
    OSS vs enterprise

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)
    Ring Logo

    Loading documentation...

    Preparing Ring content

    Ring Logo

    Loading documentation...

    Preparing Ring content

    Ring Logo

    Loading documentation...

    Preparing Ring content

    Phone OTP sign-in

    Use Founder / Developer tabs in the docs sidebar to filter this page. This is phone possession, not Sign in with Telegram and not Ring Mailer email codes.

    Shipped on Layer1

    The login field accepts email or phone. A phone starts requestPhoneLoginCode, stores a challenge, then signIn('phone-otp'). Delivery prefers Telegram Gateway. WhatsApp Cloud sends an AUTHENTICATION copy-code template only when Gateway is unset or cannot deliver, and only if the member did not opt out.

    Delivery comparison

    SituationWhat the member getsWhat you configure
    Gateway token set and Telegram can deliverCode inside TelegramTELEGRAM_GATEWAY_TOKEN
    Gateway fails (fallbackNeeded) and WhatsApp is configured, opt-out offOne WhatsApp AUTH templateWhatsApp Cloud trio below
    Gateway not configured, WhatsApp isWhatsApp onlySame WhatsApp trio
    Member checked Do not send codes via WhatsAppGateway only, or a clear errorClient flag + checkbox
    Neither railError. Classical SMS is not wired—
    Previous / mythRing equivalent
    SMS from a US long code as the WhatsApp railWhatsApp is Meta Cloud API. A carrier number can become the business sender; it does not replace the Graph send path
    Free-form WhatsApp text (“your code is …”)AUTHENTICATION template with copy-code button. Session text hits Meta error 131047
    Second login formSame EmailLoginForm — @ means email OTP, otherwise phone
    Show {digits}@your-domain as the member’s emailVirtual mailbox for Auth.js uniqueness only. Profile offers Link Email

    Why phone login matters

    Members in markets where Telegram is the default messenger can sign in without an inbox. If that number has no Telegram, WhatsApp is the second rail — one message, not both. Opt-out is a checkbox on the phone step, remembered in the browser.

    A brand-new phone creates an account. The address stored for Auth.js is internal. The profile never presents it as “your email.” The member adds a real mailbox later with the Link Email dialog.

    Typical scenarios

    UA community clone

    Inbox-first clone

    Profile verify

    Template before traffic

    WhatsApp sends nothing until Meta marks the AUTHENTICATION copy-code template Approved. Name and language in env must match WhatsApp Manager exactly (uk is not uk_UA).

    Client checkbox is a build flag

    NEXT_PUBLIC_WHATSAPP_OTP_ENABLED=true is inlined when the image is built. Setting it only on a running pod does not show the opt-out checkbox. Server send still requires the Cloud token, phone number ID, and template name.

    Request and verify

    Phone OTP request
    PiecePath
    Login UIfeatures/auth/components/email-login-form.tsx
    Client flag + opt-out storagefeatures/auth/lib/phone-login-client.ts — key ring.phoneOtp.whatsappOptOut
    Request actionapp/_actions/auth-phone-actions.ts — requestPhoneLoginCode
    Profile verifyapp/_actions/phone-otp.ts — startPhoneOtp / confirmPhoneOtp; panel features/auth/components/phone-otp-panel.tsx
    Rail selector

    Frequently asked questions

    Impact

    Does a successful Telegram send also text WhatsApp?

    No. One request, one rail. WhatsApp runs only after Gateway is missing or returns fallbackNeeded, and only when the member has not opted out.

    Will the profile show 380…@our-domain?

    No. That mailbox satisfies users.email uniqueness. Link Email replaces it with a real address. Ring Mailer must not send login mail to a virtual address.

    Migration

    We only had email OTP

    Leave phone env unset. The unified field still routes addresses that contain @ to Ring Mailer.

    Our phone_login_tokens.request_id is VARCHAR(128)

    Apply 049_phone_login_tokens_code_hash.sql before WhatsApp. Cloud message ids can exceed 128 characters. The migration also adds nullable code_hash.

    Ops

    Graph error 132001 or 132000

    132001 — template name or language does not match an approved template. 132000 — parameter count does not match the template (body and button both need the code).

    Graph error 131026

    The number cannot receive WhatsApp. The send is treated as undeliverable. Do not retry in a loop.

    Opt-out checkbox missing in production

    NEXT_PUBLIC_WHATSAPP_OTP_ENABLED was not present at build. Rebuild the image. Runtime Secret alone does not rewrite the client bundle.

    Related documentation

    Related documentation

    Authentication

    Prerequisite: Auth.js provider list, vitals gate, and Telegram Login versus phone OTP.

    Ring Mailer & RingdomX Mail

    Same-workflow: email OTP when the identifier contains @.

    Authentication Architecture

    Deep-dive: auth.ts versus auth.config.ts and the Credentials authorize path.

    Authentication Examples

    Next-step: signIn patterns for the other Credentials providers.

    1. Docs
    2. /Features
    3. /Phone OTP sign-in

    Updated Nov 5, 20266 min listen

    Phone OTP sign-in

    Use Founder / Developer tabs in the docs sidebar to filter this page. This is phone possession, not Sign in with Telegram and not Ring Mailer email codes.

    Shipped on Layer1

    The login field accepts email or phone. A phone starts requestPhoneLoginCode, stores a challenge, then signIn('phone-otp'). Delivery prefers Telegram Gateway. WhatsApp Cloud sends an AUTHENTICATION copy-code template only when Gateway is unset or cannot deliver, and only if the member did not opt out.

    Delivery comparison

    SituationWhat the member getsWhat you configure
    Gateway token set and Telegram can deliverCode inside TelegramTELEGRAM_GATEWAY_TOKEN
    Gateway fails (fallbackNeeded) and WhatsApp is configured, opt-out offOne WhatsApp AUTH templateWhatsApp Cloud trio below
    Gateway not configured, WhatsApp isWhatsApp onlySame WhatsApp trio
    Member checked Do not send codes via WhatsAppGateway only, or a clear errorClient flag + checkbox
    Neither railError. Classical SMS is not wired—
    Previous / mythRing equivalent
    SMS from a US long code as the WhatsApp railWhatsApp is Meta Cloud API. A carrier number can become the business sender; it does not replace the Graph send path
    Free-form WhatsApp text (“your code is …”)AUTHENTICATION template with copy-code button. Session text hits Meta error 131047
    Second login formSame EmailLoginForm — @ means email OTP, otherwise phone
    Show {digits}@your-domain as the member’s emailVirtual mailbox for Auth.js uniqueness only. Profile offers Link Email

    Why phone login matters

    Members in markets where Telegram is the default messenger can sign in without an inbox. If that number has no Telegram, WhatsApp is the second rail — one message, not both. Opt-out is a checkbox on the phone step, remembered in the browser.

    A brand-new phone creates an account. The address stored for Auth.js is internal. The profile never presents it as “your email.” The member adds a real mailbox later with the Link Email dialog.

    Typical scenarios

    UA community clone

    Inbox-first clone

    Profile verify

    Template before traffic

    WhatsApp sends nothing until Meta marks the AUTHENTICATION copy-code template Approved. Name and language in env must match WhatsApp Manager exactly (uk is not uk_UA).

    Client checkbox is a build flag

    NEXT_PUBLIC_WHATSAPP_OTP_ENABLED=true is inlined when the image is built. Setting it only on a running pod does not show the opt-out checkbox. Server send still requires the Cloud token, phone number ID, and template name.

    Request and verify

    Phone OTP request
    PiecePath
    Login UIfeatures/auth/components/email-login-form.tsx
    Client flag + opt-out storagefeatures/auth/lib/phone-login-client.ts — key ring.phoneOtp.whatsappOptOut
    Request actionapp/_actions/auth-phone-actions.ts — requestPhoneLoginCode
    Profile verifyapp/_actions/phone-otp.ts — startPhoneOtp / confirmPhoneOtp; panel features/auth/components/phone-otp-panel.tsx
    Rail selector

    Frequently asked questions

    Impact

    Does a successful Telegram send also text WhatsApp?

    No. One request, one rail. WhatsApp runs only after Gateway is missing or returns fallbackNeeded, and only when the member has not opted out.

    Will the profile show 380…@our-domain?

    No. That mailbox satisfies users.email uniqueness. Link Email replaces it with a real address. Ring Mailer must not send login mail to a virtual address.

    Migration

    We only had email OTP

    Leave phone env unset. The unified field still routes addresses that contain @ to Ring Mailer.

    Our phone_login_tokens.request_id is VARCHAR(128)

    Apply 049_phone_login_tokens_code_hash.sql before WhatsApp. Cloud message ids can exceed 128 characters. The migration also adds nullable code_hash.

    Ops

    Graph error 132001 or 132000

    132001 — template name or language does not match an approved template. 132000 — parameter count does not match the template (body and button both need the code).

    Graph error 131026

    The number cannot receive WhatsApp. The send is treated as undeliverable. Do not retry in a loop.

    Opt-out checkbox missing in production

    NEXT_PUBLIC_WHATSAPP_OTP_ENABLED was not present at build. Rebuild the image. Runtime Secret alone does not rewrite the client bundle.

    Related documentation

    Related documentation

    Authentication

    Prerequisite: Auth.js provider list, vitals gate, and Telegram Login versus phone OTP.

    Ring Mailer & RingdomX Mail

    Same-workflow: email OTP when the identifier contains @.

    Authentication Architecture

    Deep-dive: auth.ts versus auth.config.ts and the Credentials authorize path.

    Authentication Examples

    Next-step: signIn patterns for the other Credentials providers.

    1. Docs
    2. /Features
    3. /Phone OTP sign-in

    Updated Nov 5, 20266 min listen

    Phone OTP sign-in

    Use Founder / Developer tabs in the docs sidebar to filter this page. This is phone possession, not Sign in with Telegram and not Ring Mailer email codes.

    Shipped on Layer1

    The login field accepts email or phone. A phone starts requestPhoneLoginCode, stores a challenge, then signIn('phone-otp'). Delivery prefers Telegram Gateway. WhatsApp Cloud sends an AUTHENTICATION copy-code template only when Gateway is unset or cannot deliver, and only if the member did not opt out.

    Delivery comparison

    SituationWhat the member getsWhat you configure
    Gateway token set and Telegram can deliverCode inside TelegramTELEGRAM_GATEWAY_TOKEN
    Gateway fails (fallbackNeeded) and WhatsApp is configured, opt-out offOne WhatsApp AUTH templateWhatsApp Cloud trio below
    Gateway not configured, WhatsApp isWhatsApp onlySame WhatsApp trio
    Member checked Do not send codes via WhatsAppGateway only, or a clear errorClient flag + checkbox
    Neither railError. Classical SMS is not wired—
    Previous / mythRing equivalent
    SMS from a US long code as the WhatsApp railWhatsApp is Meta Cloud API. A carrier number can become the business sender; it does not replace the Graph send path
    Free-form WhatsApp text (“your code is …”)AUTHENTICATION template with copy-code button. Session text hits Meta error 131047
    Second login formSame EmailLoginForm — @ means email OTP, otherwise phone
    Show {digits}@your-domain as the member’s emailVirtual mailbox for Auth.js uniqueness only. Profile offers Link Email

    Why phone login matters

    Members in markets where Telegram is the default messenger can sign in without an inbox. If that number has no Telegram, WhatsApp is the second rail — one message, not both. Opt-out is a checkbox on the phone step, remembered in the browser.

    A brand-new phone creates an account. The address stored for Auth.js is internal. The profile never presents it as “your email.” The member adds a real mailbox later with the Link Email dialog.

    Typical scenarios

    UA community clone

    Inbox-first clone

    Profile verify

    Template before traffic

    WhatsApp sends nothing until Meta marks the AUTHENTICATION copy-code template Approved. Name and language in env must match WhatsApp Manager exactly (uk is not uk_UA).

    Client checkbox is a build flag

    NEXT_PUBLIC_WHATSAPP_OTP_ENABLED=true is inlined when the image is built. Setting it only on a running pod does not show the opt-out checkbox. Server send still requires the Cloud token, phone number ID, and template name.

    Request and verify

    Phone OTP request
    PiecePath
    Login UIfeatures/auth/components/email-login-form.tsx
    Client flag + opt-out storagefeatures/auth/lib/phone-login-client.ts — key ring.phoneOtp.whatsappOptOut
    Request actionapp/_actions/auth-phone-actions.ts — requestPhoneLoginCode
    Profile verifyapp/_actions/phone-otp.ts — startPhoneOtp / confirmPhoneOtp; panel features/auth/components/phone-otp-panel.tsx
    Rail selector

    Frequently asked questions

    Impact

    Does a successful Telegram send also text WhatsApp?

    No. One request, one rail. WhatsApp runs only after Gateway is missing or returns fallbackNeeded, and only when the member has not opted out.

    Will the profile show 380…@our-domain?

    No. That mailbox satisfies users.email uniqueness. Link Email replaces it with a real address. Ring Mailer must not send login mail to a virtual address.

    Migration

    We only had email OTP

    Leave phone env unset. The unified field still routes addresses that contain @ to Ring Mailer.

    Our phone_login_tokens.request_id is VARCHAR(128)

    Apply 049_phone_login_tokens_code_hash.sql before WhatsApp. Cloud message ids can exceed 128 characters. The migration also adds nullable code_hash.

    Ops

    Graph error 132001 or 132000

    132001 — template name or language does not match an approved template. 132000 — parameter count does not match the template (body and button both need the code).

    Graph error 131026

    The number cannot receive WhatsApp. The send is treated as undeliverable. Do not retry in a loop.

    Opt-out checkbox missing in production

    NEXT_PUBLIC_WHATSAPP_OTP_ENABLED was not present at build. Rebuild the image. Runtime Secret alone does not rewrite the client bundle.

    Related documentation

    Related documentation

    Authentication

    Prerequisite: Auth.js provider list, vitals gate, and Telegram Login versus phone OTP.

    Ring Mailer & RingdomX Mail

    Same-workflow: email OTP when the identifier contains @.

    Authentication Architecture

    Deep-dive: auth.ts versus auth.config.ts and the Credentials authorize path.

    Authentication Examples

    Next-step: signIn patterns for the other Credentials providers.

    1. Docs
    2. /Features
    3. /Phone OTP sign-in

    Updated Nov 5, 20266 min listen

    features/auth/services/phone-otp-delivery.ts
    Gateway clientfeatures/auth/services/telegram-gateway-otp.ts
    WhatsApp clientfeatures/auth/services/whatsapp-cloud-otp.ts
    Challenge storefeatures/auth/services/phone-login-tokens.ts
    Auth.jsauth.ts Credentials id phone-otp
    E.164lib/phone/e164.ts — normalizeToE164
    Virtual mailboxlib/auth/virtual-email.ts — digits @ contact-email host, or auth.virtualEmailDomain
    Code helperslib/auth/email-tokens.ts — generateOTP, hmacOTP, verifyOTPTiming
    Schemadata/migrations/047_phone_login_tokens.sql, 049_phone_login_tokens_code_hash.sql

    Verify rules

    RailHow the code is checkedStored secret
    telegram_gatewaycheckVerificationStatus must return code_validrequest_id only
    whatsapphmacOTP(code, E.164) compared with verifyOTPTimingcode_hash only. Raw code is never inserted

    Challenge TTL is 3 minutes. Request cap is 5 / 15 minutes per phone. Verify cap is 5 attempts. WhatsApp bumps attempts inside verifyPhoneOtpCode; auth.ts does not bump again for that channel. A WhatsApp send without rawCode is refused before insert.

    Gateway-generated codes stay on Telegram’s API. Do not hash them into code_hash.

    WhatsApp send contract

    POST https://graph.facebook.com/{WHATSAPP_GRAPH_API_VERSION}/{WHATSAPP_CLOUD_PHONE_NUMBER_ID}/messages

    Template category AUTHENTICATION, button type copy code. The same 6-digit code is the body parameter and the URL button parameter (sub_type: url, index: "0"). Recipient to is E.164 digits without +. Default Graph version in code is v21.0 when WHATSAPP_GRAPH_API_VERSION is unset. Default template language in code is en_US when WHATSAPP_AUTH_TEMPLATE_LANG is unset — set the env to the approved locale.

    request_id prefers the Cloud message id (wamid.…, column VARCHAR(255)).

    Manual path

    1. 1

      Prerequisites

      AUTH_SECRET (min 16 characters) or OTP_HMAC_SECRET. PostgreSQL with migrations 047 and 049 applied. Phone login does not use SMTP.

    2. 2

      Enable Telegram Gateway

      Set TELEGRAM_GATEWAY_TOKEN (server only). Optional: TELEGRAM_GATEWAY_SENDER_USERNAME. TELEGRAM_GATEWAY_CALLBACK_URL is read if set; there is no /api/auth/phone-otp/callback route in this build — verify does not depend on it.

    3. 3

      Enable WhatsApp fallback

      Create an AUTHENTICATION copy-code template in WhatsApp Manager (security recommendation on, expiration 3 minutes). After status Approved, set:

      WHATSAPP_CLOUD_TOKEN, WHATSAPP_CLOUD_PHONE_NUMBER_ID (Cloud phone number ID, not the display number), WHATSAPP_AUTH_TEMPLATE_NAME, WHATSAPP_AUTH_TEMPLATE_LANG.

      Bake NEXT_PUBLIC_WHATSAPP_OTP_ENABLED=true at image build so the opt-out checkbox renders.

    4. 4

      Smoke

      With only Gateway: banner says Telegram. With Gateway unable to deliver and WhatsApp configured: one WhatsApp message, banner says WhatsApp. With opt-out: WhatsApp is not selected. Profile Send code uses the same sendPhoneOtp façade.

    Do not log the code

    rawCode exists only between WhatsApp send and insertPhoneLoginToken. Logs must not include the Graph body or the code.

    Authentication

    See-also: session endpoints — phone login still ends in an Auth.js JWT.

    Environment Configuration

    Depends-on: where AUTH_SECRET and SMTP live beside these phone vars.

    features/auth/services/phone-otp-delivery.ts
    Gateway clientfeatures/auth/services/telegram-gateway-otp.ts
    WhatsApp clientfeatures/auth/services/whatsapp-cloud-otp.ts
    Challenge storefeatures/auth/services/phone-login-tokens.ts
    Auth.jsauth.ts Credentials id phone-otp
    E.164lib/phone/e164.ts — normalizeToE164
    Virtual mailboxlib/auth/virtual-email.ts — digits @ contact-email host, or auth.virtualEmailDomain
    Code helperslib/auth/email-tokens.ts — generateOTP, hmacOTP, verifyOTPTiming
    Schemadata/migrations/047_phone_login_tokens.sql, 049_phone_login_tokens_code_hash.sql

    Verify rules

    RailHow the code is checkedStored secret
    telegram_gatewaycheckVerificationStatus must return code_validrequest_id only
    whatsapphmacOTP(code, E.164) compared with verifyOTPTimingcode_hash only. Raw code is never inserted

    Challenge TTL is 3 minutes. Request cap is 5 / 15 minutes per phone. Verify cap is 5 attempts. WhatsApp bumps attempts inside verifyPhoneOtpCode; auth.ts does not bump again for that channel. A WhatsApp send without rawCode is refused before insert.

    Gateway-generated codes stay on Telegram’s API. Do not hash them into code_hash.

    WhatsApp send contract

    POST https://graph.facebook.com/{WHATSAPP_GRAPH_API_VERSION}/{WHATSAPP_CLOUD_PHONE_NUMBER_ID}/messages

    Template category AUTHENTICATION, button type copy code. The same 6-digit code is the body parameter and the URL button parameter (sub_type: url, index: "0"). Recipient to is E.164 digits without +. Default Graph version in code is v21.0 when WHATSAPP_GRAPH_API_VERSION is unset. Default template language in code is en_US when WHATSAPP_AUTH_TEMPLATE_LANG is unset — set the env to the approved locale.

    request_id prefers the Cloud message id (wamid.…, column VARCHAR(255)).

    Manual path

    1. 1

      Prerequisites

      AUTH_SECRET (min 16 characters) or OTP_HMAC_SECRET. PostgreSQL with migrations 047 and 049 applied. Phone login does not use SMTP.

    2. 2

      Enable Telegram Gateway

      Set TELEGRAM_GATEWAY_TOKEN (server only). Optional: TELEGRAM_GATEWAY_SENDER_USERNAME. TELEGRAM_GATEWAY_CALLBACK_URL is read if set; there is no /api/auth/phone-otp/callback route in this build — verify does not depend on it.

    3. 3

      Enable WhatsApp fallback

      Create an AUTHENTICATION copy-code template in WhatsApp Manager (security recommendation on, expiration 3 minutes). After status Approved, set:

      WHATSAPP_CLOUD_TOKEN, WHATSAPP_CLOUD_PHONE_NUMBER_ID (Cloud phone number ID, not the display number), WHATSAPP_AUTH_TEMPLATE_NAME, WHATSAPP_AUTH_TEMPLATE_LANG.

      Bake NEXT_PUBLIC_WHATSAPP_OTP_ENABLED=true at image build so the opt-out checkbox renders.

    4. 4

      Smoke

      With only Gateway: banner says Telegram. With Gateway unable to deliver and WhatsApp configured: one WhatsApp message, banner says WhatsApp. With opt-out: WhatsApp is not selected. Profile Send code uses the same sendPhoneOtp façade.

    Do not log the code

    rawCode exists only between WhatsApp send and insertPhoneLoginToken. Logs must not include the Graph body or the code.

    Authentication

    See-also: session endpoints — phone login still ends in an Auth.js JWT.

    Environment Configuration

    Depends-on: where AUTH_SECRET and SMTP live beside these phone vars.

    features/auth/services/phone-otp-delivery.ts
    Gateway clientfeatures/auth/services/telegram-gateway-otp.ts
    WhatsApp clientfeatures/auth/services/whatsapp-cloud-otp.ts
    Challenge storefeatures/auth/services/phone-login-tokens.ts
    Auth.jsauth.ts Credentials id phone-otp
    E.164lib/phone/e164.ts — normalizeToE164
    Virtual mailboxlib/auth/virtual-email.ts — digits @ contact-email host, or auth.virtualEmailDomain
    Code helperslib/auth/email-tokens.ts — generateOTP, hmacOTP, verifyOTPTiming
    Schemadata/migrations/047_phone_login_tokens.sql, 049_phone_login_tokens_code_hash.sql

    Verify rules

    RailHow the code is checkedStored secret
    telegram_gatewaycheckVerificationStatus must return code_validrequest_id only
    whatsapphmacOTP(code, E.164) compared with verifyOTPTimingcode_hash only. Raw code is never inserted

    Challenge TTL is 3 minutes. Request cap is 5 / 15 minutes per phone. Verify cap is 5 attempts. WhatsApp bumps attempts inside verifyPhoneOtpCode; auth.ts does not bump again for that channel. A WhatsApp send without rawCode is refused before insert.

    Gateway-generated codes stay on Telegram’s API. Do not hash them into code_hash.

    WhatsApp send contract

    POST https://graph.facebook.com/{WHATSAPP_GRAPH_API_VERSION}/{WHATSAPP_CLOUD_PHONE_NUMBER_ID}/messages

    Template category AUTHENTICATION, button type copy code. The same 6-digit code is the body parameter and the URL button parameter (sub_type: url, index: "0"). Recipient to is E.164 digits without +. Default Graph version in code is v21.0 when WHATSAPP_GRAPH_API_VERSION is unset. Default template language in code is en_US when WHATSAPP_AUTH_TEMPLATE_LANG is unset — set the env to the approved locale.

    request_id prefers the Cloud message id (wamid.…, column VARCHAR(255)).

    Manual path

    1. 1

      Prerequisites

      AUTH_SECRET (min 16 characters) or OTP_HMAC_SECRET. PostgreSQL with migrations 047 and 049 applied. Phone login does not use SMTP.

    2. 2

      Enable Telegram Gateway

      Set TELEGRAM_GATEWAY_TOKEN (server only). Optional: TELEGRAM_GATEWAY_SENDER_USERNAME. TELEGRAM_GATEWAY_CALLBACK_URL is read if set; there is no /api/auth/phone-otp/callback route in this build — verify does not depend on it.

    3. 3

      Enable WhatsApp fallback

      Create an AUTHENTICATION copy-code template in WhatsApp Manager (security recommendation on, expiration 3 minutes). After status Approved, set:

      WHATSAPP_CLOUD_TOKEN, WHATSAPP_CLOUD_PHONE_NUMBER_ID (Cloud phone number ID, not the display number), WHATSAPP_AUTH_TEMPLATE_NAME, WHATSAPP_AUTH_TEMPLATE_LANG.

      Bake NEXT_PUBLIC_WHATSAPP_OTP_ENABLED=true at image build so the opt-out checkbox renders.

    4. 4

      Smoke

      With only Gateway: banner says Telegram. With Gateway unable to deliver and WhatsApp configured: one WhatsApp message, banner says WhatsApp. With opt-out: WhatsApp is not selected. Profile Send code uses the same sendPhoneOtp façade.

    Do not log the code

    rawCode exists only between WhatsApp send and insertPhoneLoginToken. Logs must not include the Graph body or the code.

    Authentication

    See-also: session endpoints — phone login still ends in an Auth.js JWT.

    Environment Configuration

    Depends-on: where AUTH_SECRET and SMTP live beside these phone vars.