A passcode must last long enough to arrive and be entered, while limiting the opportunity to guess or reuse it. Measure the complete verification flow before choosing its duration.
How long should the passcode stay valid?
Allow no more than ten minutes for a sent authentication code, including delivery and entry.
NIST's authentication guidance sets that maximum for authentication through a separate channel. It also requires the server to accept the code only once, preventing reuse after successful authentication.
Mark the code used when it succeeds. Reject another submission of that code even if it arrives before expiry.
Ten minutes is a maximum rather than a recommended waiting period. Choose a shorter window when your delivery and entry measurements support it.
A code that takes forty seconds to arrive leaves nine minutes and twenty seconds in a ten-minute window. Include reading and typing time when using your arrival measurements.
Authenticator-generated codes follow a different timing model. Use the corresponding TOTP or HOTP rules when the application generates the code locally.
How many digits should it have?
Use at least six digits generated randomly. Set a limit on failed guesses.
NIST requires at least six decimal digits from an approved random generator for sent authentication secrets. A predictable counter or timestamp does not meet that requirement.
Six random digits give one million possible codes. Five distinct guesses have five chances in one million, or one in two hundred thousand.
Count failed attempts against the account. NIST requires a new code to preserve that count, so resending cannot create unlimited guesses.
An attempt cap also needs a recovery path for legitimate users who exhaust it. Decide how they regain access without resetting the cap for an attacker.
Should I use eight digits instead?
Use eight when the smaller guessing probability justifies two more digits for the person to enter.
Eight random digits give one hundred million possible codes. With five guesses, the chance becomes five in one hundred million.
That is one hundred times lower than five guesses against six digits. Keep the same attempt limit when increasing the code length.
Longer codes do not repair unlimited guessing. Implement the attempt limit before treating extra digits as sufficient protection.
What can I configure in Bird?
Set the workspace's passcode policy. Inspect the resolved settings returned for each verification.
| Field | What to choose |
|---|---|
code_length | Bird accepts 4 to 8 characters. Choose at least six for this policy |
code_type | Inspect the returned character set, numeric or alphanumeric |
ttl_seconds | Bird accepts 1 to 59940 seconds. Keep the authentication window at 600 seconds or less |
max_attempts | Choose 1 to 10 incorrect submissions before the verification fails |
resend_cooldown_seconds | Choose 0 to 3600 seconds between sends to the recipient |
The API's allowed duration extends beyond this authentication recommendation. Set the value deliberately instead of treating the maximum accepted value as a suitable expiry.
A verification request can override code_length for that verification. Check its resolved policy when investigating behavior that differs from the workspace configuration.
What should I choose?
- Start with six random digits and a small, enforced attempt cap.
- Size the validity window from measured delivery and entry time, within ten minutes.
- Use eight digits when the action warrants a smaller guessing probability.
- Enforce single use and preserve failed-attempt counts when issuing another code.
In short
Allow no more than ten minutes.
Delivery and entry both consume the validity window. Choose a shorter duration when your measured flow supports it.
Use at least six random digits.
Count failed guesses as well as choosing a code length. Longer codes do not replace an attempt limit.
Accept each code only once.
Reject a previously accepted code even if its validity window has not ended.
Keep attempt counts through resends.
Issuing another code must not give the account a fresh supply of guesses.