Contents

POST /solve/$NONCE#

Used by the user-agent to submit an answer to the challenge. If the answer is correct, the user will be redirected to the client’s redirect URI, otherwise the user may be given another chance to complete the process.

Request:

Body should use the mime-type “application/x-www-form-urlencoded”. The posted form data must contain a “pin” field.

Response:

200 OK:

If the request ask for application/json the response is a ChallengeSolveResponse. Since protocol v2.

302 Found:

Only possible if request didn’t ask for application/json. Since protocol v2. The user is redirected to the redirect URI of the client to pass the grant to the client. The target will be the redirect URI specified by the client (during registration and again upon /authorize), plus a code argument with the authorization code, and the state argument from the /authorize endpoint.

400 Bad Request:

The request does not follow the spec. The response will include error code, hint and detail. Since protocol v1.

403 Forbidden:

The response is InvalidPinResponse. Since protocol v1.

404 Not found:

The service is unaware of a matching challenge. The response will include error code, hint and detail. Since protocol v1.

429 Too Many Requests:

There have been too many attempts to solve the challenge for this address (and $NONCE). The user-agent should either try a different address (or wait and (eventually) request a fresh nonce to be set up by the client). The response will include error code, hint and detail. Since protocol v2.

500 Internal Server Error:

Server is not able to respond due to internal problems. The response will include error code, hint and detail. Since protocol v1.

// Union discriminated by the "type" field.
type ChallengeSolveResponse = ChallengeRedirect | InvalidPinResponse;

interface InvalidPinResponse {
  // Union discriminator field.
  type: "pending";

  // numeric Taler error code, should be shown to indicate the error
  // compactly for reporting to developers
  code: Integer;

  // human-readable Taler error code, should be shown for the user to
  // understand the error
  hint: string;

  // how many times is the user still allowed to change the address;
  // if 0, the user should not be shown a link to jump to the
  // address entry form
  addresses_left: Integer;

  // how many times might the PIN still be retransmitted
  pin_transmissions_left: Integer;

  // how many times might the user still try entering the PIN code
  auth_attempts_left: Integer;

  // if true, the PIN was not even evaluated as the user previously
  // exhausted the number of attempts
  exhausted: boolean;

  // if true, the PIN was not even evaluated as no challenge was ever
  // issued (the user must have skipped the step of providing their
  // address first!)
  no_challenge: boolean;
}
Contents