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ù

La lunghezza predefinita del codice di Bird rispetta NIST SP 800-63B, mentre options.code_length accetta anche codici più corti (Opzioni). Per l'autenticazione mantieni il valore predefinito o uno più lungo:

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

Il valore predefinito di Duration coincide con il tetto dello standard, mentre l'impostazione dello spazio di lavoro accetta finestre più lunghe (Impostazioni di verifica):

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

Alzare Duration oltre 10 minuti 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 limita quanti controlli errati accetta una verifica prima di fallire con attempts_exhausted (Impostazioni di verifica). Lo standard richiede questo limite per un codice così breve e aggiunge una regola:

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

Poiché Maximum Retries ha un massimo ben inferiore a 100, nessuna configurazione a tua disposizione supera il tetto dello standard. È 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: i limiti orari di invio per destinatario (tra avvio e reinvio) e i limiti di controlli al minuto restituiscono entrambi 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, Telegram e voce (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, Telegram e chiamate vocali 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 determinano la strategia per i nuovi tentativi, cioè quando e come riprovare:

• Una verifica che passa attraverso più canali costa più invii, quindi un piano canali ampio è una decisione di costo tanto quanto di consegna.
• Poiché Telegram addebita quando un numero raggiungibile viene accettato per la consegna, e non alla ricezione di una conferma di consegna (Costi e fatturazione), un tentativo Telegram che poi non viene consegnato resta addebitato quando la sessione passa al canale successivo. Rimuovi Telegram dall'ordine dei canali nella pagina Destinations per le destinazioni in cui vuoi evitare quel costo di fallback.

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
• Destinations: ordine e disponibilità dei canali per paese
• Mittenti e branding: l'aspetto di ogni messaggio