taler-docs

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

post-token.rst (3156B)

      1 .. http:post:: /token
      2 
      3   This is the token endpoint of the OAuth 2.0 specification.
      4   This endpoint is used by the client to provide its authorization code,
      5   demonstrating that it has the right to learn a particular user's validated
      6   address.  In return, the challenger service returns the access token.
      7   Renewal is not supported.
      8 
      9   **Request:**
     10 
     11   The request must include an ``application/www-form-urlencoded`` body
     12   specifying the ``client_id``, ``redirect_uri``, ``client_secret``, ``code``
     13   and ``grant_type``.  The ``grant_type`` must be set to
     14   ``authorization_code``.  The ``redirect_uri`` must match the URI from
     15   ``/authorize``. The ``code`` must be the authorization code that ``/solve``
     16   returned to the user.  The ``client_id`` and ``client_secret`` must match
     17   the usual client credentials. Since protocol **v3**, ``code_verifier`` can also be included.
     18 
     19   **Response:**
     20 
     21   Error responses follow RFC 6749, section 5.2 with an "error" field in JSON,
     22   as well as also returning GNU Taler style error messages.
     23 
     24   :http:statuscode:`200 OK`:
     25     The body will be a `ChallengerAuthResponse`.
     26   :http:statuscode:`400 Bad Request`:
     27     A required POST field (``grant_type``, ``client_id``,
     28     ``client_secret``, ``code`` or ``redirect_uri``) is missing
     29     or malformed, or ``grant_type`` is not ``authorization_code``.
     30     Usually returned with ``TALER_EC_GENERIC_PARAMETER_MISSING``
     31     or ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     32   :http:statuscode:`401 Unauthorized`:
     33     Authentication of the client failed.  Returned (per
     34     RFC 6749, section 5.2) when the client credentials are
     35     invalid, when the supplied ``code`` is malformed or does
     36     not match the validation, when the ``redirect_uri`` does
     37     not match the one registered with the client, or when the
     38     ``code_verifier`` does not match the saved
     39     ``code_challenge``.  Returned with
     40     ``TALER_EC_CHALLENGER_GENERIC_CLIENT_FORBIDDEN_BAD_REDIRECT_URI``,
     41     ``TALER_EC_CHALLENGER_CLIENT_FORBIDDEN_BAD_CODE``,
     42     ``TALER_EC_CHALLENGER_GENERIC_CLIENT_UNKNOWN``,
     43     ``TALER_EC_CHALLENGER_GENERIC_VALIDATION_UNKNOWN`` or
     44     ``TALER_EC_CHALLENGER_GRANT_UNKNOWN``.
     45     PKCE-related rejections are since protocol **v3**.
     46   :http:statuscode:`409 Conflict`:
     47     A ``code`` was presented for a validation process for which
     48     the user has not (yet) submitted any address, so the token
     49     cannot be issued.  Returned with
     50     ``TALER_EC_CHALLENGER_MISSING_ADDRESS``.
     51   :http:statuscode:`500 Internal Server Error`:
     52     The challenger service encountered an internal error,
     53     for example a database failure or a failure of the SHA-256
     54     or Base64 helpers used for PKCE verification.
     55     Error codes used are:
     56     * ``TALER_EC_CHALLENGER_GENERIC_DB_FETCH_FAILED``
     57     * ``TALER_EC_CHALLENGER_GENERIC_DB_STORE_FAILED``
     58 
     59   **Details::**
     60 
     61   .. ts:def:: ChallengerAuthResponse
     62 
     63     interface ChallengerAuthResponse {
     64       // Token used to authenticate access in ``/info``.
     65       access_token: string;
     66 
     67       // Type of the access token.
     68       token_type: "Bearer";
     69 
     70       // Amount of time that an access token is valid (in seconds).
     71       expires_in: Integer;
     72 
     73     }