taler-docs

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

post-challenge-NONCE.rst (3472B)

      1 .. http:post:: /challenge/$NONCE
      2 
      3   This endpoint is used by the user-agent to submit the address to which a
      4   challenge should be sent by the challenger service.
      5 
      6   **Request:**
      7 
      8   Body should use the mime-type "application/x-www-form-urlencoded".
      9   The posted form data must contain an address JSON object
     10   that follow the restrictions
     11   defined in :ref:`config <challenger-config>`.
     12   If the address provided in the `ChallengeSetupRequest`
     13   of ``/setup`` was set to be ``read_only`` and
     14   that was subsequently returned in the
     15   `ChallengeStatusResponse`, then the body
     16   must not change that address, including preservation of the
     17   ``read_only`` field.
     18 
     19   **Response:**
     20 
     21   :http:statuscode:`200 OK`:
     22     The response is `ChallengeResponse`. Since protocol **v2**.
     23   :http:statuscode:`400 Bad Request`:
     24     The request does not follow the spec.
     25     The response will include error
     26     code, hint and detail. Since protocol **v1**.
     27   :http:statuscode:`403 Forbidden`:
     28     The address being submitted differs from the previously
     29     submitted address but the validation process was set up
     30     as ``read_only`` and thus the address cannot be changed.
     31     Returned with
     32     ``TALER_EC_CHALLENGER_CLIENT_FORBIDDEN_READ_ONLY``.
     33     Since protocol **v4**.
     34   :http:statuscode:`404 Not Found`:
     35     The service is unaware of a matching challenge.
     36     The response will include error
     37     code, hint and detail. Since protocol **v1**.
     38   :http:statuscode:`429 Too Many Requests`:
     39     There have been too many attempts to request challenge
     40     transmissions for this $NONCE. The user-agent should
     41     wait and (eventually) request a fresh nonce to be set
     42     up by the client.
     43     Returned with ``TALER_EC_CHALLENGER_TOO_MANY_ATTEMPTS``.
     44     Since protocol **v2**.
     45   :http:statuscode:`500 Internal Server Error`:
     46     Server is not able to respond due to internal problems.
     47     The response will include error
     48     code, hint and detail. Since protocol **v1**.
     49   :http:statuscode:`502 Bad Gateway`:
     50     The challenger service failed to launch or communicate with
     51     its helper process for delivering the challenge (SMS, e-mail,
     52     postal mail).  Returned with
     53     ``TALER_EC_CHALLENGER_HELPER_EXEC_FAILED``.
     54 
     55   .. ts:def:: ChallengeResponse
     56 
     57     // Union discriminated by the "type" field.
     58     type ChallengeResponse = ChallengeRedirect | ChallengeCreateResponse
     59 
     60   .. ts:def:: ChallengeRedirect
     61 
     62     // @since **v2**
     63     interface ChallengeRedirect {
     64       // Union discriminator field.
     65       type: "completed";
     66 
     67       // challenge is completed, use should redirect here
     68       redirect_url: string;
     69     }
     70 
     71   .. ts:def:: ChallengeCreateResponse
     72 
     73    interface ChallengeCreateResponse {
     74       // Union discriminator field.
     75       type: "created"
     76 
     77       // how many more attempts are allowed, might be shown to the user,
     78       // highlighting might be appropriate for low values such as 1 or 2 (the
     79       // form will never be used if the value is zero)
     80       attempts_left: Integer;
     81 
     82       // the address that is being validated, might be shown or not
     83       address: Object;
     84 
     85       // true if we just retransmitted the challenge, false if we sent a
     86       // challenge recently and thus refused to transmit it again this time;
     87       // might make a useful hint to the user
     88       transmitted: boolean;
     89 
     90       // when we would re-transmit the challenge the next
     91       // time (at the earliest) if requested by the user
     92       // @since **v2**
     93       retransmission_time: Timestamp;
     94     }