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

Les codes de Bird sont par défaut à 6 chiffres et options.code_length accepte de 4 à 8 par requête (Paramètres de vérification). La valeur par défaut est le bon choix, et le bas de cette plage ne l'est pas :

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

Duration est par défaut à 10 minutes et accepte de 1 à 999 (Paramètres de vérification). La valeur par défaut se situe exactement au plafond de la norme :

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

La plage dépasse donc largement la limite. Augmenter Duration 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 est par défaut à 5 et accepte de 1 à 10 ; au-delà, la vérification échoue avec attempts_exhausted. La norme exige que cette borne existe pour un code aussi court, et ajoute une règle à connaître :

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

Maximum Retries plafonne à 10, donc aucune configuration que vous pouvez choisir n'atteint 100. 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 : 5 envois par adresse par heure glissante entre créations et renvois, et 10 vérifications par ensemble d'adresses destinataires par minute. Les deux renvoient 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 et Telegram (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 et Telegram 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é, un nouvel essai 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 une politique de nouvel essai :

• 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 à un moment différent. Telegram est interrogé pour savoir si le numéro peut recevoir un message, et le coût s'applique lorsque la réponse est oui, à un tarif forfaitaire mondial. Un numéro injoignable est gratuit et passe au canal suivant sans rien facturer. Un coût signifie donc accepté pour livraison et non arrivé : un code qui n'est finalement pas livré reste facturé, et la vérification paie de nouveau pour le canal vers lequel elle bascule. Si ce second coût n'est pas souhaité, retirez Telegram de l'ordre des canaux pour ces pays sur la page Countries (Coûts et facturation).

É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
• Countries : ordre et disponibilité des canaux par pays
• Expéditeurs et image de marque : l'apparence de chaque message