Bonnes pratiques Verify

Verify est livré avec des valeurs par défaut adaptées à la plupart des flux de codes de vérification à usage unique. Ce guide couvre les décisions que les valeurs par défaut ne prennent pas à votre place : combien de temps un code doit rester valide, combien de chiffres il lui faut, quel canal convient à ce que vous vérifiez réellement, et comment distinguer un problème de livraison d'un problème de vérification.

Lorsqu'une norme publique se prononce, ce guide la cite. La norme de référence pour l'authentification par code de vérification est NIST SP 800-63B, Digital Identity Guidelines: Authentication and Authenticator Management, consultée le 3 septembre 2026. Les citations proviennent de la révision en vigueur. L'ancienne Revision 3, que de nombreux conseils OTP citent encore, porte le propre bandeau du NIST : superseded by SP 800-63-4 as of 1 August 2025.

Gardez le code à six chiffres ou plus

La longueur de code par défaut de Bird respecte NIST SP 800-63B, mais options.code_length accepte aussi des codes plus courts (Options). Pour l'authentification, conservez la valeur par défaut ou une longueur supérieure :

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 code à 4 ou 5 chiffres est dans ce que API accepte et en dehors de ce que la norme autorise. Ne raccourcissez un code que pour un flux où vous avez décidé que l'entropie du code de vérification n'assure pas le rôle de sécurité.

Gardez la durée de vie à dix minutes ou moins

La valeur par défaut de Duration se situe au plafond de la norme, alors que le réglage de l'espace de travail accepte des fenêtres plus longues (Paramètres de vérification) :

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

Augmenter Duration au-delà de 10 minutes pour réduire les demandes de support liées aux codes expirés est le seul changement de réglage qui fait sortir discrètement un flux de 800-63B. Si les codes expirent avant que les utilisateurs ne les consultent, la solution se trouve généralement dans le chemin d'envoi plutôt que dans la fenêtre de validité.

Prévoyez deux niveaux de limitation du débit

Une tentative de vérification est bornée deux fois, et les deux limites répondent à des menaces différentes.

Votre réglage. Maximum Retries limite le nombre de vérifications incorrectes qu'une vérification accepte avant d'échouer avec attempts_exhausted (Paramètres de vérification). La norme exige cette limite pour un code aussi court et y ajoute une règle :

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

La borne a un plafond, et c'est le seul point où chaque valeur proposée par Verify se situe confortablement dans la norme :

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

Comme Maximum Retries est plafonné bien en dessous de 100, aucune configuration que vous pouvez choisir ne dépasse le plafond de la norme. C'est le miroir des deux sections précédentes : la longueur du code et la durée de vie ont chacune une valeur acceptée qui sort de 800-63B, alors que la limite de tentatives n'en a aucune.

Les plafonds de la plateforme Bird, qui s'appliquent quelle que soit votre configuration : les plafonds d'envoi horaires par destinataire (créations et renvois confondus) et les plafonds de vérification par minute renvoient tous deux 429 avec un en-tête Retry-After (Garde-fous anti-abus). Ils existent pour empêcher que le trafic OTP soit utilisé comme arme contre votre budget ou le téléphone d'un inconnu ; considérez donc un 429 ici comme le système qui fonctionne, et non comme une limite à contourner.

Choisissez le canal en fonction de ce que vous vérifiez

Verify envoie par e-mail, SMS, WhatsApp, Telegram et appel vocal (Canaux). La norme traite deux d'entre eux très différemment, et la distinction porte sur l'objectif du code plutôt que sur le canal qui le transporte.

L'e-mail n'est pas un facteur d'authentification. 800-63B est catégorique :

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

Le même passage prévoit le cas pour lequel le canal e-mail de Verify est conçu :

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.

Un code envoyé par e-mail qui prouve que quelqu'un contrôle une adresse entre dans le cadre de l'exception de la norme et convient. Un code envoyé par e-mail utilisé comme second facteur à la connexion ne convient pas. Si votre flux correspond au second cas, n'utilisez pas le canal e-mail.

SMS et la voix sont autorisés mais soumis à restrictions. La livraison via le réseau téléphonique impose trois obligations, en deux phrases consécutives :

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 est une exigence produit et non un réglage Verify : si SMS est votre seul facteur, vous ne la remplissez pas. L'ordre des canaux par pays de Verify facilite la livraison, car WhatsApp est essayé en premier dans la plupart des pays avec SMS en repli (Canaux), mais SMS, WhatsApp, Telegram et les appels vocaux sont tous des chemins de livraison pour un seul type d'authentifiant, hors bande ; passer de l'un à l'autre ne constitue donc pas une offre de type alternatif. Les deux SHOULD sont celles qu'une équipe produit implémente : une mention au moment où un utilisateur associe un numéro de téléphone, et une vérification des signaux de portabilité et de changement de SIM avant d'envoyer un code à ce numéro.

Analysez un échec avant de renvoyer

Un code qui n'arrive pas et un code qui arrive mais est mal saisi nécessitent un traitement différent, et les événements permettent de les distinguer (Événements).

verify.attempt.undelivered contient un reason, et la suite dépend du plan de canaux du destinataire. Sur un destinataire disposant de plusieurs canaux, cela ne met pas fin à la vérification : Bird passe au canal suivant, qui reçoit son propre verify.attempt.sent, de sorte qu'une seule tentative non livrée n'est pas une vérification morte et ne nécessite aucun renvoi de votre part. Sur un destinataire à canal unique, il n'y a rien vers quoi avancer, et la vérification se termine.

Cette fin nécessite un traitement spécifique, et un événement l'identifie. Le statut failed est partagé : une vérification y aboutit aussi bien quand trop de codes de vérification incorrects ont été soumis, avec reason attempts_exhausted, que quand aucun canal prévu n'a pu en livrer un, avec reason undeliverable. Seul le second cas émet verify.verification.failed. Sur un destinataire à canal unique, c'est donc cet événement, et non le statut, qui vous indique que personne n'a reçu de code.

Une propriété à intégrer dès la conception plutôt qu'à découvrir, et celle-ci est propre à Bird et non à la norme : Événements précise que les accusés de réception sont indicatifs et non garantis, car les opérateurs et les fournisseurs de messagerie varient dans ce qu'ils confirment et à quelle vitesse. Dans certains marchés, un événement de tentative arrive avec des minutes de retard ou ne distingue pas la livraison de l'acceptation. Construisez le chemin de "I didn't get a code" sur POST /v1/verify/verifications/next-channel, qui fait avancer la vérification, plutôt que sur l'attente d'un événement de livraison qui pourrait ne jamais arriver.

Réessayez la requête, pas la vérification

Les trois endpoints de Verify acceptent Idempotency-Key (Réessayer en toute sécurité). Après un délai d'attente dépassé ou une connexion coupée, réessayer avec la même clé rejoue la réponse d'origine : aucun second code n'est envoyé et aucune tentative de vérification n'est consommée. Sans clé, une nouvelle tentative après une réponse perdue envoie un autre code et consomme un envoi supplémentaire sur le plafond horaire.

Connaissez le coût d'un envoi

La facturation s'applique à chaque code envoyé, au tarif du canal pour la destination, et un renvoi ou un repli ajoute un coût par envoi (Coûts et facturation). Deux conséquences orientent votre politique de nouvelle tentative, c'est-à-dire la façon dont vous choisissez de réessayer :

• Une vérification qui passe par plusieurs canaux coûte plusieurs envois ; un plan de canaux large est donc autant une décision de coût qu'une décision de livraison.
• Telegram facture lorsqu'un numéro joignable est accepté pour livraison, et non à la réception d'un accusé de livraison (Coûts et facturation). Une tentative Telegram qui n'est finalement pas livrée reste donc facturée lorsque la session bascule vers le canal suivant. Pour les destinations où vous voulez éviter ce coût de repli, retirez Telegram de l'ordre des canaux sur la page Destinations.

Étapes suivantes

• Envoi de vérifications : les réglages, les garde-fous et la liste complète des statuts
• Événements : chaque événement de session et de livraison avec sa charge utile
• Destinations : ordre et disponibilité des canaux par pays
• Expéditeurs et image de marque : l'apparence de chaque message