Skip to main content

Choosing a Code Type

Overview#

Code generation is a key component to many different authentication related use cases. These use cases include:

  • Adding a New Device: After a user has registered their first device, they will likely want to add one or more additional devices. This could be simply their laptop and their mobile phone, or it could be numerous devices.
  • One-Time Authentication: Granting access to a device one time, best to be used when logging in on a device which you don’t own or on a device which doesn’t support FIDO.
  • Account Recovery: When a user no longer has access to their previously registered authenticator, they will need to be able to regain access to their account.

All codes are associated with a specific user, and have a default time to live (TTL), which varies depending on the entropy in the code. However, there is functionality to invalidate a code before the original expiry, which can be invoked at any time to invalidate all codes for a given user and purpose.

Code generation has an authorize parameter. This parameter indicates whether the user must authorize the code before using that code for the specified purpose (e.g. adding a new authenticator), or if the user is able to use the code immediately. Typically this value should be set to false unless being generated by an admin user or system after validating the user is who they say they are.

Short Codes#

These codes are best used when the user will be required to enter the code.

Short codes are 6 digit codes, similar to what would be typically sent in SMS or Emails as one-time-passwords (OTPs). These codes have a default TTL of 3 minutes to protect against the low entropy of the code.

An example short code is: 123456

Long Codes#

These codes are best used when the user is involved, but doesn’t directly need to be aware of the code. This includes sending emails, push notifications, or generating QR codes.

Long codes are base64URL encoded strings of 24 random bytes. These codes have a default TTL of 1 hour, as there is sufficient entropy to allow for the extended TTL.

An example long code is: MTUyIDE0NyAxMTYgMTM4IDI0OCAxMDMgMTg2IDIzOSAxNzUgMTgwIDIxOSAgNzMgICA5ICA0MiAgODMgIDMzIAogOTUgMjE3IDE3MyAgNDggIDU2IDI1MCAyNTMgIDYzIA

Phrase Codes#

The codes are best used when the user will be required to enter a code, but would likely need to write it down in order to use it later.

Phrase codes are BIP-39 passphrases. These codes have a default TTL of 24 hours.

An example phrase code is: used ugly donate rebuild crash delay hold erase total board engage arctic popular peace wisdom faith