One-time code format

Ory Kratos Identities sends one-time codes to a user's email address or phone number during login, registration, verification, and account recovery, and when the code method is used as a second factor. By default, each code has six digits.

You can change the format of these codes with two settings:

• length sets the number of characters in a code. It must be between 6 and 20. The default is 6.
• alphabet sets the characters a code is made of:
  • digits uses the digits 0 to 9. This is the default.
  • alphanumeric uses lowercase letters and digits, without characters that are easy to confuse, such as 0 and o or 1 and l. Users can enter these codes in uppercase or lowercase.

A longer code, or one that includes letters, is harder to guess but takes users longer to type. The format applies to codes sent after you change it. Codes sent earlier stay valid until they expire.

Ory CLI

1. Download the Ory Kratos Identities config from your project and save it to a file:

   ## List all available workspaces
   ory list workspaces
   
   ## List all available projects
   ory list projects --workspace <workspace-id>
   
   ## Get config
   ory get identity-config --project <project-id> --workspace <workspace-id> --format yaml > identity-config.yaml

2. Set the code format:

   identity-config.yaml

   selfservice:
     methods:
       code:
         config:
           length: 12
           alphabet: alphanumeric

3. Update the Ory Kratos Identities configuration using the file you worked with:

   ory update identity-config --project <project-id> --workspace <workspace-id> --file identity-config.yaml

Self-hosted

Set the code format in the Ory Kratos Identities configuration file:

kratos.yml

selfservice:
  methods:
    code:
      config:
        length: 12
        alphabet: alphanumeric

User interface

The code input node in the flow's UI carries attributes that match the configured format:

• maxlength is the code length.
• pattern accepts only characters of the configured alphabet. It doesn't check the length, so the flow reports a code that is too short as invalid.
• inputmode is numeric for digit codes and text for alphanumeric codes, so mobile devices show the right keyboard.

Ory Elements and Ory Account Experience show one box per character for codes of up to eight characters, and a single text field for longer codes. If you build your own UI, render these attributes on the code input.

If your custom email or SMS templates describe the code, for example as a six-digit code, update the text to match the new format.