Skip to content

docs: add docs for verify_new_address and notify_previous_addresses #2597

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jonas-jonas wants to merge 3 commits into
base: master
Choose a base branch
from
+211 −7
Open

docs: add docs for verify_new_address and notify_previous_addresses #2597

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3081850
docs: add docs for verify_new_address and notify_previous_addresses
jonas-jonas Jun 2, 2026
ddff169
Update docs/kratos/hooks/01_configure-hooks.mdx
jonas-jonas Jun 22, 2026
9571240
chore: format
jonas-jonas Jun 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions docs/actions/notify-previous-addresses.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
---
id: notify-previous-addresses
title: Notify previous addresses
---

```mdx-code-block
import Tabs from "@theme/Tabs"
import TabItem from "@theme/TabItem"
```

The `notify_previous_addresses` action sends a notification to a user's previous email or phone addresses when they change a
verifiable address through the settings flow. Use it to alert users to address changes on their account so they can react if a
change was not made by them.
Comment thread
jonas-jonas marked this conversation as resolved.

The action runs on the `after` settings flow for the `profile` method, after the change is persisted. Notification delivery never
blocks or fails the settings flow: if a message can't be queued, Ory logs a warning and the flow still succeeds.

## Choose which addresses to notify

The `recipients` configuration controls which of the user's previous addresses receive a notification:

| Value | Notifies |
| :------------- | :----------------------------------------------------------------------- |
| `removed` | Only the addresses that were removed by the change. This is the default. |
| `all_verified` | All of the user's previously verified addresses. |
| `all` | All of the user's previous addresses, whether or not they were verified. |

Only email and phone (SMS) addresses are notified. Ory sends notifications only when the set of verifiable addresses actually
changes. Changing a verification status alone does not trigger a notification.

## Enable the action

Enable `notify_previous_addresses` using either the Ory Console or the Ory CLI.

```mdx-code-block
<Tabs>
<TabItem value="console" label="Ory Console" default>
```

1. Go to <ConsoleLink route="project.verification" />.
2. Enable **Self-service Settings: Notify previous addresses**.
3. Select which addresses to notify under **Notify previous addresses recipients**.
4. Click **Save**.

```mdx-code-block
</TabItem>
<TabItem value="cli" label="Ory CLI">
```

Run:

```shell
ory patch identity-config --project <project-id> --workspace <workspace-id> \
--add '/selfservice/flows/settings/after/profile/hooks/0/hook="notify_previous_addresses"' \
--add '/selfservice/flows/settings/after/profile/hooks/0/config/recipients="all_verified"'
```

Set `recipients` to `removed`, `all_verified`, or `all`. If you omit it, Ory uses `removed`.

```mdx-code-block
</TabItem>
</Tabs>
```

:::tip

To require verification of the new address before the change is applied, combine this action with
[`verify_new_address`](verify-new-address.mdx).

:::
7 changes: 7 additions & 0 deletions docs/actions/require-verified-address.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,6 +204,13 @@ When a user updates their email address or phone number in the settings flow, Or
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.

:::tip

To require verification _before_ the new address replaces the old one, use the [`verify_new_address`](verify-new-address.mdx)
action. Unlike `show_verification_ui`, it defers the change until the user verifies the new address.

:::

### 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
Expand Down
123 changes: 123 additions & 0 deletions docs/actions/verify-new-address.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
---
id: verify-new-address
title: Verify address changes
---

```mdx-code-block
import Tabs from "@theme/Tabs"
import TabItem from "@theme/TabItem"
```

By default, when a user changes their email address or phone number in the settings flow, Ory applies the change immediately and
sends a verification code to the new address. The address stays unverified until the user completes verification, but the old
address is already replaced.

The `verify_new_address` action makes address changes safer: it defers the change until the user verifies the new address. The
identity's traits are only updated after verification completes. This prevents users from locking themselves out by entering an
address they don't control, and keeps the previous verified address in place until the new one is confirmed reachable.

## Enable verification before applying address changes

The `verify_new_address` action runs on the `after` settings flow for the `profile` method. You can enable it using either the Ory
Console or the Ory CLI.

```mdx-code-block
<Tabs>
<TabItem value="console" label="Ory Console" default>
```

1. Go to <ConsoleLink route="project.verification" />.
2. Enable **Self-service Settings: Verify new addresses**.
3. Click **Save**.

```mdx-code-block
</TabItem>
<TabItem value="cli" label="Ory CLI">
```

Run:

```shell
ory patch identity-config --project <project-id> --workspace <workspace-id> \
--add '/selfservice/flows/settings/after/profile/hooks/0/hook="verify_new_address"'
```

```mdx-code-block
</TabItem>
</Tabs>
```

## Behavior

When the action is enabled and a user changes a verifiable address in the settings flow:

- Ory keeps the current traits and creates a pending change instead of applying the update immediately.
- Ory starts a verification flow for the new address and sends a verification code to it.
- The traits update only after the user completes verification. Until then, the previous address remains in effect.

The action enforces these rules:

- **Privileged session required.** Changing an address is a sensitive update. If the session is no longer privileged, Ory asks the
user to re-authenticate before continuing.
- **One address at a time.** Ory can only verify one new address per settings submission. If the user changes more than one
verifiable address at once, the flow returns an error and applies no change.
- **No duplicate addresses.** If the new address already belongs to another identity, Ory rejects the change immediately on
submission with a duplicate credentials error, instead of failing later on the verification screen.

```mdx-code-block
<Tabs>
<TabItem value="Server rendered browser client">
```

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

```mdx-code-block
</TabItem>
<TabItem value="SPA & Native clients">
```

The settings endpoint returns the settings flow with a `continue_with` field that contains the verification flow for the new
address:

```json
{
"id": "...",
"ui": {
"action": "...",
"method": "...",
"nodes": [
/* ... */
]
},
"continue_with": [
{
"action": "show_verification_ui",
"flow": {
"id": "d859f6af-1dfe-453e-9320-d572e10edeea",
"verifiable_address": "new-address@ory.com",
"url": "https://ory.example.org/verification?flow=d859f6af-1dfe-453e-9320-d572e10edeea"
}
}
]
}
```

Send the user to the verification flow to confirm the new address. Ory applies the trait change once verification succeeds.

```mdx-code-block
</TabItem>
</Tabs>
```

:::note

The `verify_new_address` action defers the change until the new address is verified. This differs from the `show_verification_ui`
action described in [Verification on address change](require-verified-address.mdx#verification-on-address-change), which applies
the change immediately and only redirects the user to the verification screen afterwards.
Comment on lines +114 to +116

:::

## Notify previous addresses

To also notify the user's previous addresses when an address changes, combine this action with
[`notify_previous_addresses`](notify-previous-addresses.mdx).
16 changes: 9 additions & 7 deletions docs/kratos/hooks/01_configure-hooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ social sign-in provider.

### Available actions

There are 4 actions you can use to extend self-service user flows. The `web_hook` action allows you to trigger any custom,
There are 6 actions you can use to extend self-service user flows. The `web_hook` action allows you to trigger any custom,
external logic.

:::info
Expand All @@ -100,12 +100,14 @@ Some actions can only be used for specific flows and methods.

:::

| Action | Description | Details |
| :----------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`session`](../../actions/session.mdx) | Signs in the user immediately after they create an account. | For use only with the `after` registration flow. To use it, you must define secrets for secret rotation. |
| [`revoke_active_sessions`](../../actions/revoke-active-sessions.mdx) | Revokes all other active sessions of the user on successful login. | For use only with the login flow. |
| [`require_verified_address`](../../actions/require-verified-address.mdx) | Allows users to sign in only when they verified their email address. | For use only with the `after` login flow, `password` method only. |
| [`web_hook`](../../guides/integrate-with-ory-cloud-through-webhooks.mdx) | Allows to trigger external and custom logic. Can be used with all flows and methods except error and logout. | Requires providing webhook configuration. This is the only action type available for the `after` settings flow. See an example of using webhooks [here](../../guides/integrate-with-ory-cloud-through-webhooks.mdx). |
| Action | Description | Details |
| :------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`session`](../../actions/session.mdx) | Signs in the user immediately after they create an account. | For use only with the `after` registration flow. To use it, you must define secrets for secret rotation. |
| [`revoke_active_sessions`](../../actions/revoke-active-sessions.mdx) | Revokes all other active sessions of the user on successful login. | For use only with the login flow. |
| [`require_verified_address`](../../actions/require-verified-address.mdx) | Allows users to sign in only when they verified their email address. | For use only with the `after` login flow, `password` method only. |
| [`verify_new_address`](../../actions/verify-new-address.mdx) | Changes the user's address after they verify the new address. | For use only with the `after` settings flow, `profile` method only. |
| [`notify_previous_addresses`](../../actions/notify-previous-addresses.mdx) | Notifies the user's previous addresses when they change a verifiable address. | For use only with the `after` settings flow, `profile` method only. Accepts a `recipients` configuration. |
| [`web_hook`](../../guides/integrate-with-ory-cloud-through-webhooks.mdx) | Allows to trigger external and custom logic. Can be used with all flows and methods except error and logout. | Requires providing webhook configuration. It is the most common action type for the `after` settings flow. See an example of using webhooks [here](../../guides/integrate-with-ory-cloud-through-webhooks.mdx). |

### Trigger precedence

Expand Down
2 changes: 2 additions & 0 deletions sidebars-network.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -340,6 +340,8 @@ const networkSidebar = [
"actions/revoke-active-sessions",
"actions/session",
"actions/require-verified-address",
"actions/verify-new-address",
"actions/notify-previous-addresses",
{
type: "category",
label: "Integrations",
Expand Down
Loading