Email and SMS one-time-code authentication

Ory Network allows users to authenticate through a one-time code sent via email and SMS. This is useful for use-cases where users need to be onboarded through a minimal authentication process.

The one-time code method consists of a two-step process. The first step the user is required to enter their email address. In the second step they are prompted to enter the one-time code sent to their email address.

Below are examples of the one-time code authentication method in action:

https://ory.yourapp.com/

In the registration flow below we are only presented an input field for the email address, as we have not defined any other traits in the Identity Schema.

Enable email one-time-code (OTP)

1. To enable email one-time-code, enable the one-time code strategy for passwordless:

Ory Console UI

Go to Authentication → Passwordless login in the Ory Console to enable passwordless with one-time code.

Ory CLI

ory patch identity-config <your-project-id> \
  --add '/selfservice/methods/code/passwordless_enabled=true'

Full Config

config.yml

selfservice:
  methods:
    code:
      passwordless_enabled: true

2. If you are using a custom identity schema and not a preset, check the custom identity schema section.
3. Open the login UI and test it out!
4. You need a good email delivery provider to ensure that one-time codes are delivered reliably. We recommend setting up your own SMTP provider to ensure that you have full control over the email delivery process.

Enable SMS one-time-code (OTP)

1. To enable sms one-time-code, enable the one-time code strategy for passwordless:

Ory Console UI

Go to Authentication → Passwordless login in the Ory Console to enable passwordless with one-time code.

Ory CLI

ory patch identity-config <your-project-id> \
  --add '/selfservice/methods/code/passwordless_enabled=true'

Full Config

config.yml

selfservice:
  methods:
    code:
      passwordless_enabled: true

2. Select an identity schema that has a phone number. In our case we will use the sms preset:
   1. Go to User management → Identity schema in the Ory Console.
   2. Click the "active schema" drop down.
   3. Select the sms preset.
3. For this example we will create a mock SMS provider. You can find more information on how to configure SMS providers in SMS delivery configuration:
   1. Set up a fake webhook endpoint using a service like webhook.site.
   2. Copy the "unique URL" of the webhook (for example https://webhook.site/859c1c...).
   3. Use the Ory CLI to set up the SMS channel:

      ory patch identity-config --project ${project_id} \
        --add '/courier/channels=[{"id":"sms","request_config":{"method":"PUT","body":"base64://ZnVuY3Rpb24oY3R4KSB7DQpjdHg6IGN0eCwNCn0=","url":"https://webhook.site/#!/view/859c1c2c-c4d5-4058-aec4-53f37929c5c1"}}]'
4. Open the sign up page and sign up for an account.
5. After the UI shows you that a code has been sent, check out the webhook target which will now show in response to the SMS being sent.
6. If you are using a custom identity schema and not a preset, check the custom identity schema section.

Template customization

Customize the login and registration email templates to match your brand. You can find more information on how to do this in Emails and SMS.

Custom identity schema

All Ory Identity Schema presets are one-time code ready.

If you want to use a custom identity schema, you must define which field of the schema is the primary identifier for the one-time code strategy.

identity.schema.json

{
  $schema: "http://json-schema.org/draft-07/schema#",
  type: "object",
  properties: {
    traits: {
      type: "object",
      properties: {
        email: {
          type: "string",
          format: "email",
          title: "Your email",
          minLength: 3,
          "ory.sh/kratos": {
            credentials: {
              code: {
                identifier: true,
                via: "email",
              },
              // ...
            },
          },
        },
        // ...
        phone_number: {
          type: "string",
          format: "tel",
          title: "Your phone number",
          minLength: 3,
          "ory.sh/kratos": {
            credentials: {
              code: {
                identifier: true,
                via: "sms",
              },
              // ...
            },
          },
        },
      },
    },
  },
}