taler-docs

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

post-setup-CLIENT_ID.rst (2403B)

      1 .. http:post:: /setup/$CLIENT_ID
      2 
      3   This endpoint is used by the client to authorize the execution of an address
      4   validation on its behalf.  An ``Authorization`` header (for now always using
      5   a ``Bearer`` token) should be included to provide the client's credentials
      6   to authorize access to the challenger service.  This token must match the
      7   ``client_secret`` from the registration of the client with the challenger
      8   service (which will also be used in the later ``/token`` request).
      9 
     10   **Request:**
     11 
     12   The body can be an address in JSON encoding to pre-initialize the address to
     13   be used by challenger for this process. If the body is absent, the user will
     14   have to enter the full address details.  The specific address format depends
     15   on the address type.  However, `ChallengeSetupRequest` defines the shared
     16   ``read_only`` bit that has a special meaning independent of the address type:
     17   it informs Challenger that the address should not be editable.
     18 
     19   Passing an address in the ``/setup`` body is supported @since protocol **v4**.
     20 
     21   **Response:**
     22 
     23   :http:statuscode:`200 OK`:
     24     Response is a `ChallengeSetupResponse`.
     25   :http:statuscode:`400 Bad request`:
     26     The request is malformed. Usually returned with an
     27     error code of ``TALER_EC_GENERIC_PARAMETER_MISSING`` or
     28     ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     29   :http:statuscode:`404 Not found`:
     30     The challenger service is unaware of a matching client.
     31     or the credentials of the client are invalid.
     32     Usually returned with
     33     ``TALER_EC_CHALLENGER_GENERIC_CLIENT_UNKNOWN``.
     34   :http:statuscode:`500 Internal server error`:
     35     The challenger service encountered an internal error.
     36     Usually returned with
     37     ``TALER_EC_GENERIC_DB_FETCH_FAILED`` or
     38     ``TALER_EC_GENERIC_DB_STORE_FAILED`` or
     39     ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``.
     40 
     41   **Details::**
     42 
     43   .. ts:def:: ChallengeSetupRequest
     44 
     45     interface ChallengeSetupRequest {
     46       // If true, the given address should not be edited.
     47       // Defaults to 'false' if not specified.
     48       read_only?: boolean;
     49 
     50       // Optional, additional fields to pre-populate
     51       // the address to be validated.
     52       // The fields depend on the challenger type.
     53       [x: string]: any;
     54     }
     55 
     56 
     57   .. ts:def:: ChallengeSetupResponse
     58 
     59     interface ChallengeSetupResponse {
     60       // Nonce to use when constructing ``/authorize`` endpoint.
     61       nonce: string;
     62     }