taler-docs

commit 4363394cac07379265656a819050043476b3f6d0
parent d33d7f4adbacb27d33191bcbacebef5b3b9c9583
Author: Christian Grothoff <christian@grothoff.org>
Date:   Thu,  4 Sep 2025 22:22:04 +0200

add MFA to various endpoints

Diffstat:
M
core/api-merchant.rst
 | 
46
+++++++++++++++++++++++++++++++++++++---------

1 file changed, 37 insertions(+), 9 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -95,6 +95,7 @@ Examples:
 https://merchant-backend.example.com/private
    https://merchant-backend.example.com/private/auth
    https://merchant-backend.example.com/instances/$ID/private
+   https://merchant-backend.example.com/instances/$ID/forgot-password
    https://merchant-backend.example.com/instances/$ID/private/auth
 
    Unavailabe endpoints (will return 404):
@@ -1265,6 +1266,10 @@ Setting up instances
 
   **Response:**
 
+  :http:statuscode:`202 Accepted`:
+    2FA is required for this operation, usually to validate the
+    email and/or phone numbers provided for the instance.
+    This returns the `ChallengeResponse`. @since **v21**
   :http:statuscode:`204 No content`:
     The backend has successfully created the instance.
   :http:statuscode:`409 Conflict`:
@@ -1275,21 +1280,29 @@ Setting up instances
     would be if a deleted but not purged instance is known under this
     ID to the backend.
 
-.. http:post:: [/instances/$INSTANCE]/forgot-password
+.. http:post:: /instances/$INSTANCE/forgot-password
 
-  Same as ``/management/instances/$INSTANCE/auth`` it will update the password of the instance but
+  Same as ``/management/instances/$INSTANCE/private/auth`` it will update the password of the instance but
   without requiring the current password. On the first call it will validate the request
-  and return the challenge id with a 202 response. Once the challenge is solved the
-  request needs to be repeated with the ``Taler-Challenge-Ids`` header. Since protocol **v21**
+  and return the multi-factor authentication challenge IDs with
+  a ``202 Accepted`` response. Once the challenges are solved the
+  request needs to be repeated with the ``Taler-Challenge-Ids`` header.
+
+  This endpoint is **not** available for the ``admin`` instance.
+  The administrator must use the command-line tool if they forgot
+  their password.
+
+  Since protocol **v21**
 
   **Request** the request must be an `InstanceAuthConfigurationMessage`.
 
   **Response:**
 
   :http:statuscode:`202 Accepted`:
-    2FA is required for this operation. This returns the `Challenge` response. @since **v21**
+    2FA is required for this operation. This returns
+    the `ChallengeResponse`. @since **v21**
   :http:statuscode:`204 No content`:
-    The backend has successfully created the instance.
+    The backend has successfully changed the credentials for the instance.
   :http:statuscode:`404 Not found`:
     This instance is unknown and thus cannot be reconfigured.
 
@@ -1307,6 +1320,10 @@ Setting up instances
 
   **Response:**
 
+  :http:statuscode:`202 Accepted`:
+    2FA is required for this operation, usually to validate the
+    email and/or phone numbers registered for the instance.
+    This returns the `ChallengeResponse`. @since **v21**
   :http:statuscode:`204 No content`:
     The backend has successfully created the instance.
   :http:statuscode:`409 Conflict`:
@@ -1387,7 +1404,7 @@ Setting up instances
   :http:statuscode:`202 Accepted`:
     2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v21**
   :http:statuscode:`204 No content`:
-    The backend has successfully created the instance.
+    The backend has successfully changed the credentials for the instance.
   :http:statuscode:`404 Not found`:
     This instance is unknown and thus cannot be reconfigured.
 
@@ -1461,6 +1478,9 @@ Setting up instances
   :http:statuscode:`200 Ok`:
     The backend is returning the access token in a
     `LoginTokenSuccessResponse`.
+  :http:statuscode:`202 Accepted`:
+    2FA is required for this operation.
+    This returns the `ChallengeResponse`. @since **v21**
 
   **Details:**
 
@@ -1991,6 +2011,10 @@ Deleting instances
 
   **Response:**
 
+  :http:statuscode:`202 Accepted`:
+    2FA is required for this operation, usually to validate the
+    email and/or phone numbers registered for the instance.
+    This returns the `ChallengeResponse`. @since **v21**
   :http:statuscode:`204 No content`:
     The backend has successfully removed the instance.  The body is empty.
   :http:statuscode:`401 Unauthorized`:
@@ -2186,6 +2210,10 @@ into any of the active bank accounts of an instance.
 
   :http:statuscode:`200 Ok`:
     Adding the account was successful, we return the salt selected by the backend and the resulting wire hash in an `AccountAddResponse`.
+  :http:statuscode:`202 Accepted`:
+    2FA is required for this operation, usually to validate the
+    email and/or phone numbers registered for the instance.
+    This returns the `ChallengeResponse`. @since **v21**
   :http:statuscode:`404 Not found`:
     The merchant instance is unknown or it is not in our data.
   :http:statuscode:`409 Conflict`:
@@ -2266,9 +2294,9 @@ into any of the active bank accounts of an instance.
   **Response:**
 
   :http:statuscode:`204 No content`:
-    The template has successfully modified.
+    The account has successfully modified.
   :http:statuscode:`404 Not found`:
-    The template(ID) is unknown to the backend.
+    The account (``H_WIRE``) is unknown to the backend.
 
   **Details:**