API/Changing-Passwords.md

+[[Available-Endpoints]]
+
+# Changing Passwords
+
+## Set new password
+
+To set a new password, the user can call the `change_password` plugin.
+
+POST /plugins/change_password
+
+```
+#!json
+{
+    "newPassword":"maxpwd",
+    "oldPassword":"eAMBczwShhg@8s8h"
+}
+```
+
+Alternatively, if a user has edit rights on system/client, a simple transition will also set to password to that value.
+
+POST /data/system/client/1/edit
+
+```
+#!json
+{"password" : "veryveryverysafe"}
+```
+
+## Reset password
+
+In case a user has forgotten their password, two endpoints are available 
+to reset it to a random value. Note that this only works if the user has 
+a valid email address in the system.client entity.
+
+First (to make sure that the password does not get reset by anybody
+unautorized), the `/request_password_reset` endpoint will send an email with
+a reset token to the user:
+
+GET /request_password_reset?email=example@email.address
+
+```
+#!json
+{
+  "success": true,
+  "message": "The email to reset the password has been sent."
+}
+
+```
+
+Callig the URL included in the email will then reset the password to a random value which is returned. With this password, the user can log in, get a token and reset their password (see above /plugins/change_password).
+
+GET /password_reset?token=77d327fb-c010-4807-976f-a95b3d91be4f
+
+```
+#!json
+{
+  "password": "5e6ff4db"
+}
+```
+
+For development and testing, the gateway environment variable `GW_TEST` can be set
+to a true value (e.g. in the docker-compose.yaml) and the token will
+be returned instead.
+
+```
+#!json
+{
+  "token": "5e6ff4db-8a13-4469-bc0d-d501b11379f8"
+}
+```
\ No newline at end of file