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 Standard-Codelänge von Bird erfüllt NIST SP 800-63B, während options.code_length auch kürzere Codes akzeptiert (Optionen). Behalten Sie für die Authentifizierung den Standardwert bei oder wählen Sie längere Codes:

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

Die Standard-Duration liegt genau an der Obergrenze des Standards, während die Workspace-Einstellung längere Zeitfenster akzeptiert (Verifizierungseinstellungen):

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

Duration über 10 Minuten zu erhöhen, um Supportanfragen wegen abgelaufener Codes zu reduzieren, ist die eine Einstellungsänderung, die einen Flow unbemerkt 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 legt fest, wie viele falsche Prüfungen eine Verifizierung akzeptiert, bevor sie mit attempts_exhausted fehlschlägt (Verifizierungseinstellungen). Der Standard verlangt diese Grenze für einen so kurzen Code 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

Da Maximum Retries deutlich unter 100 begrenzt ist, überschreitet keine Konfiguration, die Sie wählen können, die Obergrenze des Standards. 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: Stündliche Versandobergrenzen pro Empfänger (über Starten und erneutes Senden hinweg) und Prüfobergrenzen pro Minute geben beide 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, Telegram und Sprachanruf 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 Sprachanrufe 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, Telegram und Sprachanrufe 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 an diese Nummer.

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.

Versuchen Sie die Anfrage erneut, 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, wie Sie erneute Versuche planen:

• Eine Verifizierung, die mehrere Kanäle durchläuft, kostet mehrere Sendungen. Ein breiter Kanalplan ist daher ebenso eine Kostenentscheidung wie eine Zustellentscheidung.
• Telegram berechnet die Gebühr, sobald eine erreichbare Nummer zur Zustellung angenommen wird, und nicht erst bei einer Zustellbestätigung (Kosten und Abrechnung). Ein Telegram-Versuch, der später nicht zugestellt wird, bleibt daher berechnet, wenn die Session auf den nächsten Kanal zurückfällt. Entfernen Sie Telegram auf der Seite Destinations aus der Kanalreihenfolge für die Ziele, bei denen Sie diese Fallback-Kosten vermeiden möchten.

Nächste Schritte

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