Best practice per Verify

Verify viene fornito con valori predefiniti adatti alla maggior parte dei flussi con codice di verifica monouso. Questa guida copre le decisioni che i valori predefiniti non prendono al posto tuo: quanto deve durare un codice, quante cifre servono, quale canale è appropriato per ciò che stai effettivamente verificando e come distinguere un problema di consegna da un problema di verifica.

Dove uno standard pubblico ha una posizione, questa guida lo cita. Lo standard per l'autenticazione con codice di verifica è NIST SP 800-63B, Digital Identity Guidelines: Authentication and Authenticator Management, consultato il 3 settembre 2026. Le citazioni provengono dalla revisione corrente. La precedente Revision 3, che molti consigli OTP citano ancora, riporta l'avviso dello stesso NIST: sostituita da SP 800-63-4 dal 1° agosto 2025.

Mantieni il codice a sei cifre o più

I codici di Bird hanno come valore predefinito 6 cifre e options.code_length accetta da 4 a 8 per richiesta (Impostazioni di verifica). Il valore predefinito è la scelta giusta, il limite inferiore dell'intervallo no:

The verifier SHALL generate random authentication secrets that are at least six decimal digits (or equivalent) in length using an approved random bit generator

Un codice a 4 o 5 cifre rientra in ciò che API accetta ma esce da ciò che lo standard consente. Accorcia un codice solo per un flusso in cui hai deciso che l'entropia del codice di verifica non è il meccanismo che garantisce la sicurezza.

Mantieni la durata a dieci minuti o meno

Duration ha come valore predefinito 10 minuti e accetta da 1 a 999 (Impostazioni di verifica). Il valore predefinito si posiziona esattamente sul tetto dello standard:

In all cases, the authentication SHALL be considered invalid unless completed within 10 minutes.

Quindi l'intervallo va ben oltre il limite. Alzare Duration per ridurre le richieste di assistenza sui codici scaduti è l'unica modifica che porta silenziosamente un flusso fuori da 800-63B. Se i codici scadono prima che gli utenti li raggiungano, la soluzione di solito sta nel percorso di invio, non nella finestra temporale.

Prevedi due livelli di limitazione delle richieste

Un tentativo di verifica è limitato due volte, e i due limiti rispondono a minacce diverse.

La tua impostazione. Maximum Retries ha come valore predefinito 5 e accetta da 1 a 10; oltre questo limite la verifica fallisce con attempts_exhausted. Lo standard richiede che questo vincolo esista per un codice così breve, e aggiunge una regola che vale la pena conoscere:

Generating a new authentication secret SHALL NOT reset the failed authentication count.

Il vincolo ha un tetto, e questo è l'unico punto in cui ogni valore offerto da Verify è comodamente dentro lo standard:

the verifier SHALL limit consecutive failed authentication attempts using a specific authenticator on a single subscriber account to no more than 100 by disabling that authenticator

Maximum Retries arriva al massimo a 10, quindi nessuna configurazione a tua disposizione raggiunge 100. È lo specchio delle due sezioni precedenti: lunghezza del codice e durata hanno ciascuna un valore supportato che esce da 800-63B, mentre il limite di tentativi non ne ha.

I limiti di piattaforma di Bird, che si applicano indipendentemente dalla tua configurazione: 5 invii per indirizzo per ora mobile tra avvio e reinvio, e 10 controlli per set di indirizzi destinatario al minuto. Entrambi restituiscono 429 con un header Retry-After (Protezioni anti-abuso). Esistono per impedire che il traffico OTP venga usato come arma contro il tuo portafoglio o il dispositivo di qualcuno, quindi considera un 429 qui come il sistema che funziona correttamente, non come un limite da aggirare.

Scegli il canale in base a ciò che stai verificando

Verify consegna tramite email, SMS, WhatsApp e Telegram (Canali). Lo standard tratta due di questi in modo molto diverso, e la distinzione riguarda lo scopo del codice, non quale canale lo trasporta.

L'email non è un fattore di autenticazione. 800-63B è categorico:

Email SHALL NOT be used for out-of-band authentication because it may be vulnerable to:

• Access using only a password
• Interception in transit or at intermediate mail servers
• Rerouting attacks, such as those caused by Domain Name System (DNS) spoofing

Lo stesso passaggio prevede un'eccezione per il caso per cui il canale email di Verify è progettato:

Confirmation codes that are sent to validate email addresses or are issued as recovery codes (see Sec. 4.2.1.2) are not authentication processes and not affected by the above prohibition.

Quindi un codice email che dimostra il controllo di un indirizzo rientra nell'eccezione dello standard ed è legittimo. Un codice email usato come secondo fattore al momento del login no. Se il tuo flusso è il secondo, non ricorrere al canale email.

SMS e voce sono consentiti ma con restrizioni. La consegna attraverso la rete telefonica comporta tre obblighi, in due frasi consecutive:

Accordingly, verifiers SHALL ensure that alternative authenticator types are available to all subscribers and SHOULD remind subscribers of this limitation of PSTN out-of-band authenticators before binding one or more devices controlled by the subscriber. Verifiers SHOULD consider risk indicators (e.g., device swap, SIM change, number porting, other abnormal behavior) before using the PSTN to deliver an out-of-band authentication secret.

SHALL è un requisito di prodotto, non un'impostazione di Verify: se SMS è il tuo unico fattore, non lo soddisfi. L'ordine dei canali per paese di Verify aiuta con la consegna, perché WhatsApp viene tentato per primo nella maggior parte dei paesi con SMS come fallback (Canali), ma SMS, WhatsApp e Telegram sono tutti percorsi di consegna per un unico tipo di autenticatore, out-of-band, quindi passare dall'uno all'altro non significa offrire un tipo alternativo. I due SHOULD sono quelli che un team di prodotto implementa: un avviso nel punto in cui un utente associa un numero di telefono e un controllo dei segnali di portabilità e cambio SIM prima di inviare a quel numero.

Leggi l'errore prima di reinviare

Un codice che non arriva e un codice che arriva ma viene digitato male richiedono gestioni diverse, e gli eventi li distinguono (Eventi).

verify.attempt.undelivered contiene un reason, e ciò che accade dopo dipende dal piano canali del destinatario. Su un destinatario con più di un canale disponibile non termina la verifica: Bird avanza al canale successivo, che riceve il proprio verify.attempt.sent, quindi un singolo tentativo non consegnato non è una verifica fallita e non richiede un reinvio da parte tua. Su un destinatario a canale singolo non c'è niente a cui avanzare e la verifica termina.

Quella conclusione richiede una gestione a sé, e un evento la identifica. Lo stato failed è condiviso: una verifica vi arriva sia quando sono stati inviati troppi codici di verifica errati, con reason attempts_exhausted, sia quando nessun canale pianificato è riuscito a consegnarne uno, con reason undeliverable. Solo il secondo caso emette verify.verification.failed. Quindi su un destinatario a canale singolo è quell'evento, non lo stato, a dirti che nessuno ha ricevuto un codice.

Una proprietà da tenere in conto in fase di progettazione, e questa è propria di Bird piuttosto che dello standard: Eventi indica che i report di consegna sono indicativi e non garantiti, perché gli operatori e i provider di posta variano in ciò che confermano e in quanto tempo. In alcuni mercati un evento di tentativo arriva con minuti di ritardo o non distingue la consegna dall'accettazione. Costruisci il percorso di "I didn't get a code" su POST /v1/verify/verifications/next-channel, che fa avanzare la verifica, anziché attendere un evento di consegna che potrebbe non arrivare.

Riprova la richiesta, non la verifica

Tutti e tre gli endpoint di Verify accettano Idempotency-Key (Riprovare in sicurezza). Dopo un timeout o una connessione interrotta, riprovare con la stessa chiave restituisce la risposta originale: nessun secondo codice viene inviato e nessun tentativo di controllo viene consumato. Senza chiave, un nuovo tentativo dopo una risposta persa invia un altro codice e consuma un altro invio dal limite orario.

Sappi quanto costa un invio

La fatturazione si applica a ogni codice inviato, alla tariffa del canale per la destinazione, e un reinvio o un fallback aggiunge un addebito per invio (Costi e fatturazione). Due conseguenze condizionano una policy di ripetizione:

• Una verifica che passa attraverso più canali costa più invii, quindi un piano canali ampio è una decisione di costo tanto quanto di consegna.
• Telegram fattura in un momento diverso. A Telegram viene chiesto se il numero può ricevere un messaggio, e l'addebito scatta quando la risposta è sì, a tariffa fissa mondiale. Un numero non raggiungibile è gratuito e avanza al canale successivo senza nulla in fattura. Quindi un addebito significa accettato per la consegna, non arrivato: un codice che poi non viene consegnato resta addebitato, e la verifica paga di nuovo per il canale a cui ricade. Se quel secondo addebito non è desiderato, rimuovi Telegram dall'ordine dei canali per quei paesi nella pagina Countries (Costi e fatturazione).

Prossimi passi

• Invio delle verifiche: le impostazioni, le protezioni e l'elenco completo degli stati
• Eventi: ogni evento di sessione e consegna con il relativo payload
• Countries: ordine e disponibilità dei canali per paese
• Mittenti e branding: l'aspetto di ogni messaggio