GET /info

This userinfo endpoint of the OAuth 2.0 specification. This endpoint is used by the client to obtain the user’s validated address.

Request:

Must include the token returned to the client from the /token endpoint as a Bearer token in an Authorization header. The scheme token is matched case-insensitively and may be followed by any amount of whitespace. No query parameters or request body are read.

Response:

Every error response carries an RFC 6749 section 5.2 error field in the JSON body, and every 401 additionally carries the RFC 6750 section 3 challenge:

WWW-Authenticate: Bearer realm="challenger", error="...", error_description="..."

As required by RFC 6750 section 3, the challenge answering a request that carried no authentication credentials at all names only the realm and omits both error and error_description.

200 OK:

The body contains the address as a ChallengerInfoResponse.

401 Unauthorized:

The bearer token is missing, invalid (malformed) or unknown. Error codes used are:

• TALER_EC_GENERIC_PARAMETER_MISSING — there is no Authorization header (detail is "Authorization"). Since protocol v8 the JSON body and the WWW-Authenticate challenge omit error in this case, per RFC 6750 section 3.

• TALER_EC_GENERIC_PARAMETER_MALFORMED — the Authorization header does not use the Bearer scheme (error is invalid_request, detail is "Authorization").

• TALER_EC_CHALLENGER_TOKEN_UNKNOWN — the token does not decode, is unknown, or has expired (error is invalid_token). Since protocol v8; previously TALER_EC_CHALLENGER_GRANT_UNKNOWN, which is now reserved for the authorization grant at /token so that each error code maps to exactly one HTTP status.

Note

A token that does not decode and a token that is simply unknown are answered with a byte-identical response on purpose, so that a caller cannot first learn whether a guessed token is well-formed and only then whether it exists.

404 Not found:

The bearer token is invalid (includes unknown or expired). Returned with TALER_EC_CHALLENGER_GRANT_UNKNOWN. Removed in v8 (to better match RFC 6750); the condition is now reported as 401.

405 Method Not Allowed:

The request used a method other than GET, HEAD or OPTIONS. Returned by the request router with an Allow header and an empty body; in particular there is no Taler error code. HEAD is handled exactly like GET but without a response body, as required by RFC 9110 section 9.3.2; since protocol v8.

500 Internal Server Error:

The challenger service encountered an internal error, typically a database failure. detail is "get_token" and error is server_error. Error codes used are:

• TALER_EC_GENERIC_DB_FETCH_FAILED — a hard database error.

• TALER_EC_GENERIC_DB_SOFT_FAILURE — a serialization failure that survived all retries; retrying the request may succeed. Since protocol v8, matching /token; previously this case also used TALER_EC_GENERIC_DB_FETCH_FAILED.

Details::

interface ChallengerInfoResponse {

  // Unique ID of the record within Challenger
  // (identifies the rowid of the token).
  id: Integer;

  // Address that was validated.
  // Key-value pairs, details depend on the
  // address_type.
  address: Object;

 // Type of the address.  This is the address_type of the
 // challenger service as a whole (see /config), not a
 // per-token value.
  address_type: string;

  // How long do we consider the address to be
  // valid for this user.
  expires: Timestamp;

}