From 82f505c9b6e4908a247b3a889d930bc308abe3e9 Mon Sep 17 00:00:00 2001
From: Ihor Aleksandrychiev <ihor.aleksandrychiev@northern.tech>
Date: Mon, 26 Aug 2024 12:04:47 +0300
Subject: [PATCH] Added the Reset password API documentation

Ticket: ENT-10837
Signed-off-by: Ihor Aleksandrychiev <ihor.aleksandrychiev@northern.tech>
---
 .../reset-password.markdown                   | 103 ++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 api/enterprise-api-ref/reset-password.markdown

diff --git a/api/enterprise-api-ref/reset-password.markdown b/api/enterprise-api-ref/reset-password.markdown
new file mode 100644
index 000000000..118cef46e
--- /dev/null
+++ b/api/enterprise-api-ref/reset-password.markdown
@@ -0,0 +1,103 @@
+---
+layout: default
+title: Reset password API
+published: true
+---
+
+## Request reset password link and token
+
+This call initiates the password reset process by sending a reset password
+link and token to the user's registered email address. User can click the link from the email
+and set a new password in the Mission Portal or invalidate the request.
+Every request has an expiration time equal to 48 hours.
+
+**URI:** https://hub.cfengine.com/api/auth/password/forgot/:username
+
+**Method:** POST
+
+**Example request (curl):**
+
+```console
+curl -X POST \
+  https://hub.cfengine.com/api/auth/password/forgot/admin
+```
+
+**Successful response example:**
+
+```
+HTTP 200 Ok
+
+Reset password email successfully sent.
+```
+
+**Responses:**
+
+| HTTP response code       | Description                                                   |
+|--------------------------|---------------------------------------------------------------|
+| 200 OK                   | Check your email for the link to reset your password.         |
+| 422 Unprocessable Entity | We are unable to reset the password at this time.             |
+
+
+## Reset password by token
+
+This call provides possibility to change password by reset password token
+from the [Request reset password link and token][Reset password API#Request reset password link and token] endpoint.
+
+**URI:** https://hub.cfengine.com/api/auth/password/reset/:token
+
+**Method:** POST
+
+**Example request (curl):**
+
+```console
+curl -X POST \
+  --data-raw '{"password": "new password"}' \
+  https://hub.cfengine.com/api/auth/password/reset/v1twknmrLWos
+```
+
+**Successful response example:**
+
+```
+HTTP 200 Ok
+
+Reset password email successfully sent.
+```
+
+**Responses:**
+
+| HTTP response code       | Description                                                     |
+|--------------------------|-----------------------------------------------------------------|
+| 200 OK                   | Password successfully changed.                                  |
+| 422 Unprocessable Entity | Password validation error or the request cannot be processed.   |
+| 429 Too Many Requests    | We have detected multiple unsuccessful reset password attempts. |
+
+
+## Invalidate reset password token
+
+This call provides possibility to invalidate reset password token
+from the [Request reset password link and token][Reset password API#Request reset password link and token] endpoint.
+
+**URI:** https://hub.cfengine.com/api/auth/password/reset/:token
+
+**Method:** DELETE
+
+**Example request (curl):**
+
+```console
+curl -X DELETE  https://hub.cfengine.com/api/auth/password/reset/v1twknmrLWos
+```
+
+**Successful response example:**
+
+```
+HTTP 202 Accepted
+
+Reset password token successfully invalidated.
+```
+
+**Responses:**
+
+| HTTP response code       | Description                                    |
+|--------------------------|------------------------------------------------|
+| 202 Accepted             | Reset password token successfully invalidated. |
+| 422 Unprocessable Entity | Unable to process request.                     |