Best Practices für Verify

Verify wird mit Standardwerten ausgeliefert, die für die meisten Einmalcode-Flows passen. Dieser Leitfaden behandelt die Entscheidungen, die Ihnen die Standardwerte nicht abnehmen: wie lange ein Code gültig sein soll, wie viele Stellen er braucht, welcher Kanal zu dem passt, was Sie tatsächlich verifizieren, und wie Sie ein Zustellproblem von einem Verifizierungsproblem unterscheiden.

Wo ein öffentlicher Standard eine Vorgabe macht, zitiert dieser Leitfaden ihn. Der Standard für die Authentifizierung mit Bestätigungscodes ist NIST SP 800-63B, Digital Identity Guidelines: Authentication and Authenticator Management, abgerufen am 3. September 2026. Zitate stammen aus der aktuellen Revision. Die ältere Revision 3, auf die sich viele OTP-Ratgeber noch beziehen, trägt den eigenen Hinweis von NIST: abgelöst durch SP 800-63-4 zum 1. August 2025.

Verwenden Sie mindestens sechs Stellen

Die Codes von Bird haben standardmäßig 6 Stellen und options.code_length akzeptiert 4 bis 8 pro Anfrage (Verifizierungseinstellungen). Der Standardwert ist die richtige Wahl, das untere Ende des Bereichs nicht:

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

Ein 4- oder 5-stelliger Code liegt innerhalb dessen, was die API akzeptiert, aber außerhalb dessen, was der Standard erlaubt. Kürzen Sie einen Code nur für einen Flow, in dem die Entropie des Bestätigungscodes bewusst nicht die Sicherheitsarbeit leistet.

Begrenzen Sie die Gültigkeitsdauer auf zehn Minuten oder weniger

Duration hat den Standardwert 10 Minuten und akzeptiert 1 bis 999 (Verifizierungseinstellungen). Der Standardwert liegt genau an der Obergrenze des Standards:

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

Der zulässige Bereich geht also weit über das Limit hinaus. Duration zu erhöhen, um Supportanfragen wegen abgelaufener Codes zu reduzieren, ist die eine Einstellungsänderung, die einen Flow still und leise aus 800-63B herausführt. Wenn Codes ablaufen, bevor Nutzer sie erreichen, liegt die Lösung meist im Versandweg und nicht im Zeitfenster.

Rechnen Sie mit zwei Ebenen der Begrenzung der Anfragerate

Ein Prüfversuch wird zweifach begrenzt, und die beiden Limits adressieren unterschiedliche Bedrohungen.

Ihre Einstellung. Maximum Retries hat den Standardwert 5 und akzeptiert 1 bis 10; darüber hinaus schlägt die Verifizierung mit attempts_exhausted fehl. Der Standard verlangt, dass diese Grenze für einen so kurzen Code existiert, und fügt eine Regel hinzu, die Sie kennen sollten:

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

Die Grenze hat eine Obergrenze, und dies ist die eine Stelle, an der jeder Wert, den Verify anbietet, komfortabel innerhalb des Standards liegt:

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 endet bei 10, sodass keine Konfiguration, die Sie wählen können, 100 erreicht. Das ist das Spiegelbild der beiden Abschnitte oben: Codelänge und Gültigkeitsdauer haben jeweils einen unterstützten Wert, der 800-63B verlässt, das Versuchslimit hingegen nicht.

Die Plattform-Obergrenzen von Bird, die unabhängig von Ihrer Konfiguration gelten: 5 Sendungen pro Adresse pro rollierender Stunde über Starten und erneutes Senden hinweg, sowie 10 Prüfungen pro Empfängeradress-Set pro Minute. Beide geben 429 mit einem Retry-After-Header zurück (Missbrauchsschutz). Sie verhindern, dass OTP-Traffic gegen Ihr Guthaben oder das Gerät einer fremden Person eingesetzt wird. Behandeln Sie ein 429 hier als funktionierendes System und nicht als Limit, das es zu umgehen gilt.

Wählen Sie den Kanal passend zu dem, was Sie verifizieren

Verify stellt über E-Mail, SMS, WhatsApp und Telegram zu (Kanäle). Der Standard behandelt zwei davon sehr unterschiedlich, und die Unterscheidung betrifft den Zweck des Codes, nicht den Kanal, der ihn übermittelt.

E-Mail ist kein Authentifizierungsfaktor. 800-63B ist eindeutig:

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

Dieselbe Passage beschreibt den Fall, für den der E-Mail-Kanal von Verify gedacht ist:

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.

Ein E-Mail-Code, der beweist, dass jemand eine Adresse kontrolliert, fällt unter die Ausnahme des Standards und ist zulässig. Ein E-Mail-Code, der als zweiter Faktor bei der Anmeldung dient, nicht. Wenn Ihr Flow der zweite ist, greifen Sie nicht zum E-Mail-Kanal.

SMS und Sprache sind erlaubt, aber eingeschränkt. Die Zustellung über das Telefonnetz bringt drei Pflichten mit sich, in zwei aufeinanderfolgenden Sätzen:

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.

Die SHALL ist eine Produktanforderung, keine Verify-Einstellung: Wenn SMS Ihr einziger Faktor ist, erfüllen Sie sie nicht. Die länderspezifische Kanalreihenfolge von Verify hilft bei der Zustellung, weil WhatsApp in den meisten Ländern zuerst versucht wird und SMS als Fallback dient (Kanäle). Aber SMS, WhatsApp und Telegram sind alle Zustellwege für einen Authentifikatortyp, Out-of-Band. Ein Wechsel zwischen ihnen bietet also keinen alternativen Typ. Die beiden SHOULDs sind diejenigen, die ein Produktteam implementiert: ein Hinweis an der Stelle, an der ein Nutzer eine Telefonnummer verknüpft, und eine Prüfung von Portierungs- und SIM-Wechsel-Signalen vor dem Versand.

Analysieren Sie einen Fehler, bevor Sie erneut senden

Ein Code, der nicht ankommt, und ein Code, der ankommt und falsch eingetippt wird, erfordern unterschiedliche Behandlung. Die Events unterscheiden beides (Events).

verify.attempt.undelivered enthält eine reason, und der weitere Ablauf hängt vom Kanalplan des Empfängers ab. Bei einem Empfänger mit mehr als einem verfügbaren Kanal beendet es die Verifizierung nicht: Bird rückt zum nächsten Kanal vor, der sein eigenes verify.attempt.sent erhält. Ein einzelner nicht zugestellter Versuch bedeutet also keine gescheiterte Verifizierung und erfordert kein erneutes Senden Ihrerseits. Bei einem Empfänger mit nur einem Kanal gibt es keinen nächsten Kanal, und die Verifizierung endet.

Dieses Ende erfordert eine eigene Behandlung, und ein Event identifiziert es. Der Status failed wird geteilt: Eine Verifizierung landet dort sowohl wenn zu viele falsche Bestätigungscodes eingereicht wurden, mit reason attempts_exhausted, als auch wenn kein geplanter Kanal einen zustellen konnte, mit reason undeliverable. Nur der zweite Fall löst verify.verification.failed aus. Bei einem Empfänger mit nur einem Kanal ist es also dieses Event und nicht der Status, das Ihnen sagt, dass niemand einen Code erhalten hat.

Eine Eigenschaft, die Sie einplanen sollten, statt sie erst im Betrieb zu entdecken, und diese stammt von Bird selbst, nicht vom Standard: Events stellt fest, dass Zustellberichte indikativ und nicht garantiert sind, weil Carrier und Mailbox-Anbieter sich darin unterscheiden, was sie bestätigen und wie schnell. In manchen Märkten trifft ein Versuch-Event Minuten später ein oder unterscheidet nicht zwischen Zustellung und Annahme. Bauen Sie den "I didn't get a code"-Pfad auf POST /v1/verify/verifications/next-channel auf, das die Verifizierung weiterführt, statt auf ein Zustell-Event zu warten, das möglicherweise nicht kommt.

Wiederholen Sie die Anfrage, nicht die Verifizierung

Alle drei Verify-Endpunkte akzeptieren Idempotency-Key (Sicheres Wiederholen). Nach einem Timeout oder einer abgebrochenen Verbindung gibt ein erneuter Versuch mit demselben Key die ursprüngliche Antwort zurück: Es wird kein zweiter Code versendet und kein Prüfversuch verbraucht. Ohne Key sendet ein erneuter Versuch nach einer verlorenen Antwort einen weiteren Code und verbraucht eine weitere Sendung vom stündlichen Kontingent.

Kennen Sie die Kosten pro Sendung

Die Abrechnung erfolgt pro gesendetem Code zum Kanaltarif für das Ziel, und ein erneutes Senden oder ein Fallback erzeugt eine zusätzliche Gebühr pro Sendung (Kosten und Abrechnung). Zwei Konsequenzen bestimmen Ihre Wiederholungsstrategie:

• Eine Verifizierung, die mehrere Kanäle durchläuft, kostet mehrere Sendungen. Ein breiter Kanalplan ist daher ebenso eine Kostenentscheidung wie eine Zustellentscheidung.
• Telegram rechnet an einem anderen Punkt ab. Telegram wird gefragt, ob die Nummer eine Nachricht empfangen kann, und die Gebühr fällt an, wenn die Antwort Ja lautet, zu einem weltweiten Pauschaltarif. Eine nicht erreichbare Nummer ist kostenlos und rückt zum nächsten Kanal vor, ohne dass etwas berechnet wird. Eine Gebühr bedeutet also zur Zustellung angenommen, nicht angekommen: Ein Code, der dann nicht zugestellt wird, bleibt berechnet, und die Verifizierung zahlt erneut für den Kanal, auf den sie zurückfällt. Wenn diese zweite Gebühr nicht gewünscht ist, entfernen Sie Telegram aus der Kanalreihenfolge für die betreffenden Länder auf der Countries-Seite (Kosten und Abrechnung).

Nächste Schritte

• Verifizierungen senden: die Einstellungen, der Missbrauchsschutz und die vollständige Statusliste
• Events: jedes Session- und Zustell-Event mit seinem Payload
• Countries: länderspezifische Kanalreihenfolge und Verfügbarkeit
• Absender und Branding: wie jede Nachricht aussieht