post-instances-INSTANCE-forgot-password.rst (2884B)
1 .. http:post:: /instances/$INSTANCE/forgot-password 2 3 Like ``[/instances/$INSTANCE]/private/auth``, this endpoint updates the 4 password of the instance, but it does not require the current password. 5 Instead, every TAN channel listed in ``MANDATORY_TAN_CHANNELS`` must be 6 solved. Thus, configurations listing both ``sms`` and ``email`` require 7 both challenges, while configurations listing only one of them require only 8 that channel. On the first call the backend validates the request and 9 returns the challenge IDs with a ``202 Accepted`` response. Once all 10 required challenges are solved, the exact request must be repeated with the 11 ``Taler-Challenge-Ids`` header. 12 13 This endpoint is **not** available for the ``admin`` instance. 14 The administrator must use the command-line tool if they forgot 15 their password. 16 17 Since protocol **v21**. 18 19 **Request** the request must be a `ForgotPasswordRequest`. 20 21 **Response:** 22 23 :http:statuscode:`200 Ok`: 24 The backend has successfully changed the credentials and returns a 25 refreshable ``spa`` access token in a `LoginTokenSuccessResponse`, as 26 requested with ``token_duration``. @since **v39** 27 :http:statuscode:`202 Accepted`: 28 TAN authentication is required for this operation. This returns the 29 `ChallengeResponse` with ``combi_and`` set to true. @since **v21** 30 :http:statuscode:`204 No content`: 31 The backend has successfully changed the credentials for the instance. 32 No login token was requested. 33 :http:statuscode:`403 Forbidden`: 34 MFA channels are not available for this instance. 35 Returned with ``TALER_EC_MERCHANT_GENERIC_MFA_MISSING``. 36 :http:statuscode:`404 Not found`: 37 This instance is unknown and thus cannot be reconfigured. 38 :http:statuscode:`413 Request entity too large`: 39 The uploaded body is to long, it exceeds the size limit. 40 Returned with an error code of 41 ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``. 42 :http:statuscode:`429 Too many requests`: 43 The request would have to start new MFA challenges, but a previous 44 password reset of this instance was started less than 15 minutes ago 45 and has not been completed. Any successful change of the instance 46 password lifts this limit immediately. 47 Returned with ``TALER_EC_MERCHANT_TAN_TOO_EARLY``. 48 :http:statuscode:`500 Internal Server Error`: 49 The server experienced an internal failure. 50 Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``. 51 52 **Details:** 53 54 .. ts:def:: ForgotPasswordRequest 55 56 // @since v39 57 type ForgotPasswordRequest = InstanceAuthConfigurationMessage & { 58 // If present and non-zero, issue a refreshable login token with 59 // "spa" scope after the password reset. "forever" requests a token 60 // without a finite expiration. Missing or zero preserves the 204 61 // response without a token. 62 token_duration?: RelativeTime; 63 };