zitadel/apps/docs/content/guides/integrate/login-ui/password-reset.mdx

---
title: Password Reset/Change in a Custom Login UI
sidebar_label: Password Reset/Change
---

When a user is on the password screen and has forgotten the password you will probably want them to be able to reset it by themselves.

## Flow

![](../../../../public/img/guides/login-ui/password-reset-flow.png)

## Request Password Reset

First you will have to make a request, to ask for a password reset.
The goal is to send the user a verification code, which can be entered to verify the password reset request.

There are two possible ways: You can either let ZITADEL send the notification with the verification code, or you can ask ZITADEL for returning the code and send the email by yourself.

[Request Password Reset Documentation](/reference/api/user/zitadel.user.v2.UserService.PasswordReset)

### ZITADEL sends the verification message

When you want ZITADEL to send the verification code you can define the notification channel.
Per default the verification code will be sent to the email address of the user.

Make sure to also include the URL Template to customize the reset link in the email sent to the user.

### Request

```bash
curl --request POST \
  --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/password_reset \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
  --data '{
    "sendLink": {
      "notificationType": "NOTIFICATION_TYPE_Email",
      "urlTemplate": "https://example.com/password/changey?userID={{.UserID}}&code={{.Code}}&orgID={{.OrgID}}"
    }
  }'
```

### ZITADEL returns the code

Send the request with asking for the return Code in the body of the request.

#### Request
```bash
curl --request POST \
  --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/password_reset \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
  --data '{
  "returnCode": {}
}'
```

#### Response

You will get the verification code in the response:
```bash
{
	"details": {
		"sequence": "625",
		"changeDate": "2023-06-27T15:02:10.321773Z",
		"resourceOwner": "163840776835432705"
	},
	"verificationCode": "IBJMUC"
}
```

## Send Verification Code

The verification code is generated and ZITADEL has sent it with the defined channel (email or sms) to your users.
If you have chosen to get the code back in the response, you should now send the code to your user.

## Change Password

The next screen should allow the user to enter the verification code and a new password.
From a user experience perspective it is nice to prefill the verification code, so the user doesn't have to do manually.

As soon as the user has typed the new password, you can send the change password request.
The change password request allows you to set a new password for the user.

[Change Password Documentation](/reference/api/user/zitadel.user.v2.UserService.SetPassword)

<Callout>
This request can be used in the password reset flow as well as to let your user change the password manually.
In this case it requires additionally the current password instead of the verification code.
</Callout>

### Request

```bash
curl --request POST \
  --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/password \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
  --data '{
  "newPassword": {
    "password": "Secr3tP4ssw0rd!",
    "changeRequired": false
  },
  "verificationCode": "48CDAP"
}'
```