Skip to main content

Address verification

Address verification ensures that a user’s email or phone number is valid and belongs to them. It helps prevent spam, ensures delivery of important notifications, and maintains system integrity.

Ory supports these verification policies:

  • Require verified addresses during sign up and/or login.
  • Allow optional verification. Users can choose to verify their email or phone number, but it’s not required or enforced by the UI.

Require verification on login​

To require address verification at login, use the require_verified_address action. It requires at least one verified address for the identity. You can enable it using either the Ory Console or CLI.

  1. Go to Authentication → Account verification in the Ory Console.
  2. Enable Require Verified Address for Login.
  3. Click Save.
note

If the identity schema defines multiple verifiable addresses, Ory sends a verification code to the first one and redirects the user to the verification flow.

If none of the identity's verifiable addresses are verified, a code will be sent to the first email or phone number in the list. If at least one address is verified, Ory will not ask for verification.

For HTML form submissions, the POST /self-service/login endpoint responds with an HTTP 302 redirect to the verification flow.

Legacy compatibility​

Before May 2025, require_verified_address returned a 400 error without sending a verification code. This behavior is deprecated. To re-enable it:

ory patch identity-config --project <project-id> --workspace <workspace-id> \
  --add '/feature_flags/legacy_require_verified_login_error=true'

The verification and show_verification_ui actions in login flows (but not sign up!) are also deprecated. Use require_verified_address instead.

Verification on sign up​

Ory supports two options after sign up:

Optional verification​

Users sign up without address verification, but a code is sent. They can verify later. By default, Ory follows this behavior.

Required verification​

Users must verify their address before getting a session. After registration, they’re redirected to the verification flow.

note

If the identity schema includes multiple verifiable addresses, the code is sent to the first one.

To enable this:

  1. Go to Authentication → Account verification in the Ory Console.
  2. Enable Show verification screen after password registration.

Or with the CLI:

ory patch identity-config "$PROJECT_ID" \
  --add '/selfservice/flows/registration/after/password/hooks/0/hook="show_verification_ui"' \
  --add '/selfservice/flows/registration/after/oidc/hooks/0/hook="show_verification_ui"' \
  --add '/selfservice/flows/registration/after/webauthn/hooks/0/hook="show_verification_ui"'

For browser clients using native forms, Ory redirects to the verification flow with HTTP 302.

Legacy compatibility​

In projects created before May 2025, the registration response includes continue_with even if Show verification screen after password registration is off.

To re-enable this legacy behavior:

ory patch identity-config --project <project-id> --workspace <workspace-id> \
  --add '/feature_flags/legacy_continue_with_verification_ui=true'

Verification on address change​

When a user updates their email address or phone number in the settings flow, Ory sends a verification code to the new address. By default, the settings flow will display a success message when the profile is updated, but the address remains unverified until the user completes the verification process.

Show verification screen after address change​

If you want users to be immediately redirected to verify their new address after changing it, you can configure the show_verification_ui hook for the settings flow. This will redirect the user to the verification screen instead of showing a success message.

To enable this behavior, use the Ory CLI:

ory patch identity-config {project_id} \
  --add '/selfservice/flows/settings/after/profile/hooks/0/hook="show_verification_ui"'

For browser clients using native forms, Ory redirects to the verification flow with HTTP 302.