taler-docs

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

post-setup-CLIENT_ID.rst (4302B)

      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 :http:post:`/token </token>` request).
      9 
     10   **Request:**
     11 
     12   The ``Authorization`` header is mandatory and must be of the form
     13   ``Bearer secret-token:$CLIENT_SECRET``: the value is expected to carry the
     14   RFC 8959 ``secret-token:`` prefix, and the prefix is part of the secret as
     15   stored by ``challenger-admin``.  The ``Bearer`` scheme token is matched
     16   case-insensitively.
     17 
     18   The body can be an address in JSON encoding to pre-initialize the address to
     19   be used by challenger for this process. If the body is absent, the user will
     20   have to enter the full address details.  The specific address format depends
     21   on the address type.  However, `ChallengeSetupRequest` defines the shared
     22   ``read_only`` bit that has a special meaning independent of the address type:
     23   it informs Challenger that the address should not be editable.
     24 
     25   The body is optional: a request with no body at all, or with a body of
     26   length zero, is accepted and leaves the address unset.  If a body is
     27   present it must be a JSON **object**; any other JSON value is rejected.
     28 
     29   Passing an address in the ``/setup`` body is supported @since protocol **v4**.
     30 
     31   **Response:**
     32 
     33   :http:statuscode:`200 OK`:
     34     Response is a `ChallengeSetupResponse`.
     35   :http:statuscode:`400 Bad request`:
     36     The request is malformed.  Error codes used are:
     37 
     38     * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` --- the ``$CLIENT_ID`` in the
     39       URL is not a number (``detail`` is ``"client_id"``), the body is valid
     40       JSON but not an object (``detail`` is ``"address"``), or ``read_only``
     41       is present in the body but is not a boolean (``detail`` is
     42       ``"read_only"``).
     43     * ``TALER_EC_GENERIC_JSON_INVALID`` --- the body is not well-formed JSON.
     44   :http:statuscode:`403 Forbidden`:
     45     The client did not present usable credentials.  Since protocol **v8**;
     46     previously reported as ``400``.  In both cases ``detail`` is
     47     ``"Authorization"``.  Error codes used are:
     48 
     49     * ``TALER_EC_GENERIC_PARAMETER_MISSING`` --- there is no
     50       ``Authorization`` header at all.
     51     * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` --- the header is present but
     52       does not use the ``Bearer`` scheme, or its value lacks the RFC 8959
     53       ``secret-token:`` prefix.
     54   :http:statuscode:`404 Not found`:
     55     The challenger service is unaware of a matching client,
     56     or the credentials of the client are invalid.  These two cases are
     57     deliberately not distinguished.  Always returned with
     58     ``TALER_EC_CHALLENGER_GENERIC_CLIENT_UNKNOWN``.
     59   :http:statuscode:`405 Method Not Allowed`:
     60     The request used a method other than ``POST`` or ``OPTIONS``.
     61     Returned by the request router with an ``Allow`` header and an
     62     **empty body**; in particular there is no Taler error code.
     63   :http:statuscode:`500 Internal server error`:
     64     The challenger service encountered an internal error.
     65     Error codes used are:
     66 
     67     * ``TALER_EC_GENERIC_DB_STORE_FAILED`` --- the database transaction that
     68       authenticates the client and inserts the validation failed, either
     69       hard or by exhausting the retries for serialization failures
     70       (``detail`` is ``"do_insert_validation"``).
     71     * ``TALER_EC_GENERIC_PARSER_OUT_OF_MEMORY`` --- the service ran out of
     72       memory while buffering the request body.
     73 
     74   **Details::**
     75 
     76   .. ts:def:: ChallengeSetupRequest
     77 
     78     interface ChallengeSetupRequest {
     79       // If true, the given address should not be edited.
     80       // Defaults to 'false' if not specified.
     81       read_only?: boolean;
     82 
     83       // Optional, additional fields to pre-populate
     84       // the address to be validated.
     85       // The fields depend on the challenger type.
     86       [x: string]: any;
     87     }
     88 
     89 
     90   .. ts:def:: ChallengeSetupResponse
     91 
     92     interface ChallengeSetupResponse {
     93       // Nonce to use when constructing ``/authorize`` endpoint.
     94       nonce: string;
     95     }