Dobre praktyki Verify

Verify jest dostarczany z domyślnymi ustawieniami odpowiednimi dla większości przepływów z jednorazowym kodem weryfikacyjnym. Ten przewodnik opisuje decyzje, których domyślne ustawienia nie podejmują za Ciebie: jak długo kod powinien być ważny, ile cyfr powinien mieć, który kanał jest odpowiedni do tego, co faktycznie weryfikujesz, oraz jak odróżnić problem z dostarczeniem od problemu z weryfikacją.

Tam, gdzie standard publiczny zajmuje stanowisko, ten przewodnik go cytuje. Standardem dla uwierzytelniania kodem weryfikacyjnym jest NIST SP 800-63B, Digital Identity Guidelines: Authentication and Authenticator Management, pobrano 3 września 2026. Cytaty pochodzą z bieżącej rewizji. Starsza Revision 3, na którą wciąż powołuje się wiele porad OTP, nosi własny baner NIST: zastąpiona przez SP 800-63-4 z dniem 1 sierpnia 2025.

Ustaw kod na sześć cyfr lub więcej

Kody Bird mają domyślnie 6 cyfr, a options.code_length przyjmuje od 4 do 8 na żądanie (Ustawienia weryfikacji). Wartość domyślna to właściwy wybór, a dolna granica tego zakresu nie:

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

Kod 4- lub 5-cyfrowy mieści się w tym, co API akceptuje, ale wykracza poza to, na co pozwala standard. Skracaj kod tylko w przepływie, w którym świadomie zdecydowałeś, że entropia kodu weryfikacyjnego nie odpowiada za bezpieczeństwo.

Ustaw czas życia na dziesięć minut lub mniej

Duration ma domyślną wartość 10 minut i przyjmuje od 1 do 999 (Ustawienia weryfikacji). Wartość domyślna leży dokładnie na pułapie wyznaczonym przez standard:

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

Zakres więc znacznie wykracza poza limit. Podniesienie Duration w celu zmniejszenia zgłoszeń do supportu o wygasłych kodach to jedyna zmiana ustawienia, która po cichu wyprowadza przepływ poza 800-63B. Jeśli kody wygasają, zanim użytkownicy do nich dotrą, poprawka zazwyczaj leży po stronie ścieżki wysyłki, nie okna czasowego.

Spodziewaj się dwóch warstw ograniczania liczby żądań

Próba sprawdzenia kodu jest ograniczona dwukrotnie, a oba limity odpowiadają na różne zagrożenia.

Twoje ustawienie. Maximum Retries ma domyślną wartość 5 i przyjmuje od 1 do 10; po przekroczeniu weryfikacja kończy się błędem attempts_exhausted. Standard wymaga, aby ten limit istniał dla kodu o takiej długości, i dodaje regułę wartą uwagi:

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

Limit ma pułap, i to jedyne miejsce, w którym każda wartość oferowana przez Verify mieści się komfortowo w ramach standardu:

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 sięga najwyżej 10, więc żadna konfiguracja, jaką możesz wybrać, nie osiąga 100. To lustrzane odbicie dwóch powyższych sekcji: długość kodu i czas życia mają po jednej obsługiwanej wartości, która wykracza poza 800-63B, a limit prób nie ma żadnej.

Limity platformy Bird, które obowiązują niezależnie od Twojej konfiguracji: 5 wysyłek na adres na kroczącą godzinę (łącznie rozpoczęcia i ponowne wysyłki) oraz 10 sprawdzeń na zestaw adresów odbiorcy na minutę. Oba zwracają 429 z nagłówkiem Retry-After (Zabezpieczenia przed nadużyciami). Istnieją po to, by zapobiec wykorzystaniu ruchu OTP przeciwko Twojemu portfelowi lub telefonowi obcej osoby, więc traktuj 429 jako prawidłowe działanie systemu, a nie limit do obchodzenia.

Wybierz kanał odpowiedni do tego, co weryfikujesz

Verify dostarcza kody przez e-mail, SMS, WhatsApp i Telegram (Kanały). Standard traktuje dwa z nich bardzo różnie, a rozróżnienie dotyczy tego, do czego kod służy, a nie tego, który kanał go przenosi.

E-mail nie jest czynnikiem uwierzytelniania. 800-63B jest kategoryczny:

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

Ten sam fragment wyodrębnia przypadek, do którego jest zbudowany kanał e-mail Verify:

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.

Kod e-mail potwierdzający, że ktoś kontroluje dany adres, mieści się w zakresie wyjątku standardu i jest dopuszczalny. Kod e-mail użyty jako drugi czynnik przy logowaniu już nie. Jeśli Twój przepływ to ten drugi przypadek, nie sięgaj po kanał e-mail.

SMS i połączenia głosowe są dozwolone, ale ograniczone. Dostarczanie przez sieć telefoniczną wiąże się z trzema obowiązkami, ujętymi w dwóch kolejnych zdaniach:

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 to wymaganie produktowe, a nie ustawienie Verify: jeśli SMS jest Twoim jedynym czynnikiem, nie spełniasz go. Kolejność kanałów Verify według krajów pomaga w dostarczaniu, ponieważ WhatsApp jest próbowany jako pierwszy w większości krajów z SMS jako awaryjnym (Kanały), ale SMS, WhatsApp i Telegram to ścieżki dostarczania jednego typu autentyfikatora, out-of-band, więc przełączanie między nimi nie oznacza oferowania alternatywnego typu. Dwa SHOULD to te, które wdraża zespół produktowy: informacja w momencie, gdy użytkownik wiąże numer telefonu, oraz sprawdzenie sygnałów przenoszenia numeru i zmiany SIM przed wysyłką kodu.

Odczytaj przyczynę błędu przed ponowną wysyłką

Kod, który nie dotarł, i kod, który dotarł, ale został błędnie wpisany, wymagają różnej obsługi, a zdarzenia pozwalają je rozróżnić (Zdarzenia).

verify.attempt.undelivered zawiera reason, a dalsze działanie zależy od planu kanałów odbiorcy. Dla odbiorcy z więcej niż jednym dostępnym kanałem nie kończy to weryfikacji: Bird przechodzi do następnego kanału, który otrzymuje własne verify.attempt.sent, więc pojedyncza niedostarczona próba nie jest martwą weryfikacją i nie wymaga ponownej wysyłki z Twojej strony. Dla odbiorcy z jednym kanałem nie ma do czego przejść i weryfikacja się kończy.

To zakończenie wymaga osobnej obsługi, a jedno zdarzenie je identyfikuje. Status failed jest wspólny: weryfikacja trafia do niego zarówno gdy przesłano zbyt wiele niepoprawnych kodów weryfikacyjnych, z reason attempts_exhausted, jak i gdy żaden zaplanowany kanał nie zdołał dostarczyć kodu, z reason undeliverable. Tylko drugi przypadek emituje verify.verification.failed. Zatem dla odbiorcy z jednym kanałem to właśnie to zdarzenie, a nie status, mówi Ci, że nikt nie otrzymał kodu.

Jedna właściwość, którą lepiej uwzględnić w projekcie, niż odkryć w produkcji, i ta pochodzi od Bird, a nie ze standardu: Zdarzenia informują, że raporty dostarczenia mają charakter orientacyjny, a nie gwarantowany, ponieważ operatorzy i dostawcy skrzynek pocztowych różnią się tym, co potwierdzają i jak szybko. Na niektórych rynkach zdarzenie próby przychodzi z minutowym opóźnieniem lub nie rozróżnia dostarczenia od przyjęcia. Buduj ścieżkę "I didn't get a code" na POST /v1/verify/verifications/next-channel, które przesuwa weryfikację dalej, zamiast czekać na zdarzenie dostarczenia, które może nie nadejść.

Ponawiaj żądanie, nie weryfikację

Wszystkie trzy endpointy Verify akceptują Idempotency-Key (Bezpieczne ponawianie). Po przekroczeniu limitu czasu lub zerwanym połączeniu ponowienie z tym samym kluczem odtwarza oryginalną odpowiedź: żaden drugi kod nie wychodzi i żadna próba sprawdzenia nie jest zużywana. Bez klucza ponowienie po utraconej odpowiedzi wysyła kolejny kod i zużywa kolejną wysyłkę z godzinowego limitu.

Wiedz, ile kosztuje wysyłka

Opłata jest naliczana za każdy wysłany kod, według stawki kanału dla danego miejsca docelowego, a ponowna wysyłka lub fallback dodaje opłatę za każdą wysyłkę (Koszty i rozliczenia). Dwie konsekwencje kształtują politykę ponawiania:

• Weryfikacja, która przechodzi przez kilka kanałów, kosztuje kilka wysyłek, więc szeroki plan kanałów to decyzja kosztowa w takim samym stopniu jak decyzja o dostarczalności.
• Telegram nalicza opłatę w innym momencie. Telegram jest pytany, czy numer może odebrać wiadomość, a opłata jest naliczana, gdy odpowiedź brzmi tak, według jednolitej stawki na całym świecie. Numer, do którego nie można dotrzeć, jest darmowy i przechodzi do następnego kanału bez naliczania opłaty. Opłata oznacza więc przyjęty do dostarczenia, a nie dostarczony: kod, który następnie nie zostanie dostarczony, pozostaje opłacony, a weryfikacja płaci ponownie za kanał, do którego przechodzi. Jeśli ta druga opłata nie jest pożądana, usuń Telegram z kolejności kanałów dla tych krajów na stronie Countries (Koszty i rozliczenia).

Następne kroki

• Wysyłanie weryfikacji: ustawienia, zabezpieczenia i pełna lista statusów
• Zdarzenia: wszystkie zdarzenia sesji i dostarczenia z ich ładunkiem
• Kraje: kolejność i dostępność kanałów według krajów
• Nadawcy i branding: jak wygląda każda wiadomość