Skip to main content

Password Reset/Change in a Custom Login UI

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​

Register and Login Flow

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

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​

curl --request POST \
  --url https://$ZITADEL_DOMAIN/v2beta/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​

curl --request POST \
  --url https://$ZITADEL_DOMAIN/v2beta/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:

{
    "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

note

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.

Request​

curl --request POST \
  --url https://$ZITADEL_DOMAIN/v2beta/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"
}'