taler-docs

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

get-info.rst (4163B)

      1 .. http:get:: /info
      2 
      3   This userinfo endpoint of the OAuth 2.0 specification.
      4   This endpoint is used by the client to obtain the user's validated address.
      5 
      6   **Request:**
      7 
      8   Must include the token returned to the client from the :http:post:`/token </token>` endpoint
      9   as a ``Bearer`` token in an ``Authorization`` header.  The scheme token is
     10   matched case-insensitively and may be followed by any amount of
     11   whitespace.  No query parameters or request body are read.
     12 
     13   **Response:**
     14 
     15   Every error response carries an RFC 6749 section 5.2 ``error`` field in
     16   the JSON body, and every ``401`` additionally carries the RFC 6750
     17   section 3 challenge::
     18 
     19     WWW-Authenticate: Bearer realm="challenger", error="...", error_description="..."
     20 
     21   As required by RFC 6750 section 3, the challenge answering a request that
     22   carried *no* authentication credentials at all names only the realm and
     23   omits both ``error`` and ``error_description``.
     24 
     25   :http:statuscode:`200 OK`:
     26     The body contains the address as a `ChallengerInfoResponse`.
     27   :http:statuscode:`401 Unauthorized`:
     28     The bearer token is missing, invalid (malformed) or unknown.
     29     Error codes used are:
     30 
     31     * ``TALER_EC_GENERIC_PARAMETER_MISSING`` --- there is no
     32       ``Authorization`` header (``detail`` is ``"Authorization"``).  Since
     33       protocol **v8** the JSON body and the ``WWW-Authenticate`` challenge
     34       omit ``error`` in this case, per RFC 6750 section 3.
     35     * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` --- the ``Authorization``
     36       header does not use the ``Bearer`` scheme (``error`` is
     37       ``invalid_request``, ``detail`` is ``"Authorization"``).
     38     * ``TALER_EC_CHALLENGER_TOKEN_UNKNOWN`` --- the token does not decode,
     39       is unknown, or has expired (``error`` is ``invalid_token``).
     40       Since protocol **v8**; previously
     41       ``TALER_EC_CHALLENGER_GRANT_UNKNOWN``, which is now reserved for the
     42       *authorization grant* at :http:post:`/token </token>` so that each
     43       error code maps to exactly one HTTP status.
     44 
     45     .. note::
     46 
     47       A token that does not decode and a token that is simply unknown are
     48       answered with a byte-identical response on purpose, so that a caller
     49       cannot first learn whether a guessed token is well-formed and only
     50       then whether it exists.
     51   :http:statuscode:`404 Not found`:
     52     The bearer token is invalid (includes unknown or expired).
     53     Returned with ``TALER_EC_CHALLENGER_GRANT_UNKNOWN``.
     54     Removed in **v8** (to better match RFC 6750); the condition is now
     55     reported as ``401``.
     56   :http:statuscode:`405 Method Not Allowed`:
     57     The request used a method other than ``GET``, ``HEAD`` or ``OPTIONS``.
     58     Returned by the request router with an ``Allow`` header and an
     59     **empty body**; in particular there is no Taler error code.
     60     ``HEAD`` is handled exactly like ``GET`` but without a response body,
     61     as required by RFC 9110 section 9.3.2; since protocol **v8**.
     62   :http:statuscode:`500 Internal Server Error`:
     63     The challenger service encountered an internal error,
     64     typically a database failure.  ``detail`` is ``"get_token"`` and
     65     ``error`` is ``server_error``.  Error codes used are:
     66 
     67     * ``TALER_EC_GENERIC_DB_FETCH_FAILED`` --- a hard database error.
     68     * ``TALER_EC_GENERIC_DB_SOFT_FAILURE`` --- a serialization failure that
     69       survived all retries; retrying the request may succeed.
     70       Since protocol **v8**, matching :http:post:`/token </token>`;
     71       previously this case also used
     72       ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
     73 
     74   **Details::**
     75 
     76   .. ts:def:: ChallengerInfoResponse
     77 
     78     interface ChallengerInfoResponse {
     79 
     80       // Unique ID of the record within Challenger
     81       // (identifies the rowid of the token).
     82       id: Integer;
     83 
     84       // Address that was validated.
     85       // Key-value pairs, details depend on the
     86       // address_type.
     87       address: Object;
     88 
     89      // Type of the address.  This is the ``address_type`` of the
     90      // challenger service as a whole (see ``/config``), not a
     91      // per-token value.
     92       address_type: string;
     93 
     94       // How long do we consider the address to be
     95       // valid for this user.
     96       expires: Timestamp;
     97 
     98     }