taler-docs

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

post-challenge-NONCE.rst (3425B)

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