taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

post-instances-INSTANCE-forgot-password.rst (2527B)

      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:`500 Internal Server Error`:
     43     The server experienced an internal failure.
     44     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
     45 
     46   **Details:**
     47 
     48   .. ts:def:: ForgotPasswordRequest
     49 
     50     // @since v39
     51     type ForgotPasswordRequest = InstanceAuthConfigurationMessage & {
     52       // If present and non-zero, issue a refreshable login token with
     53       // "spa" scope after the password reset. "forever" requests a token
     54       // without a finite expiration. Missing or zero preserves the 204
     55       // response without a token.
     56       token_duration?: RelativeTime;
     57     };