docs: Password reset (#6108)

* docs: add password reset to login ui guide * docs: add password reset to login ui guide * Update proto/zitadel/user/v2alpha/user_service.proto Co-authored-by: Livio Spring <livio.a@gmail.com> * Update docs/docs/guides/integrate/login-ui/password-reset.mdx Co-authored-by: Livio Spring <livio.a@gmail.com> * Update docs/docs/guides/integrate/login-ui/password-reset.mdx Co-authored-by: Livio Spring <livio.a@gmail.com> * Update docs/docs/guides/integrate/login-ui/password-reset.mdx Co-authored-by: Livio Spring <livio.a@gmail.com> * docs: replace image * docs: replace vars in urls --------- Co-authored-by: Livio Spring <livio.a@gmail.com>
2025-12-10 10:02:13 +00:00 · 2023-06-28 13:52:53 +02:00
parent bd5defa96a
commit 376d8e78b8
5 changed files with 123 additions and 16 deletions
--- a/docs/docs/guides/integrate/login-ui/password-reset.mdx
+++ b/docs/docs/guides/integrate/login-ui/password-reset.mdx
@@ -0,0 +1,106 @@
+---
+title: Password Reset/Change
+---
+
+When your user is on the password screen and has forgotten his password you will probably want him to be able to reset by himself.
+
+## Flow
+
+![Register and Login Flow](/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 he can use 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.
+
+### 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://$ZITADEL_DOMAIN/v2alpha/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://$ZITADEL_DOMAIN/v2alpha/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.
+
+:::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
+
+```bash
+curl --request POST \
+  --url https://$ZITADEL_DOMAIN/v2alpha/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"
+}'
+```
--- a/docs/docs/guides/integrate/login-ui/username-password.mdx
+++ b/docs/docs/guides/integrate/login-ui/username-password.mdx
@@ -10,7 +10,7 @@ sidebar_label: Username and Password
 ## Register

 First, we create a new user with a username and password. In the example below we add a user with profile data, a verified email address, and a password.
-[Create User Documentation](https://zitadel.com/docs/apis/resources/user_service/user-service-add-human-user)
+[Create User Documentation](/apis/resources/user_service/user-service-add-human-user)

 ### Request