POST /setup/$CLIENT_ID

This endpoint is used by the client to authorize the execution of an address validation on its behalf. An Authorization header (for now always using a Bearer token) should be included to provide the client’s credentials to authorize access to the challenger service. This token must match the client_secret from the registration of the client with the challenger service (which will also be used in the later /token request).

Request:

The body can be an address in JSON encoding to pre-initialize the address to be used by challenger for this process. If the body is absent, the user will have to enter the full address details. The specific address format depends on the address type. However, ChallengeSetupRequest defines the shared read_only bit that has a special meaning independent of the address type: it informs Challenger that the address should not be editable.

Passing an address in the /setup body is supported @since protocol v4.

Response:

200 OK:

Response is a ChallengeSetupResponse.

400 Bad request:

The request is malformed. Usually returned with an error code of TALER_EC_GENERIC_PARAMETER_MISSING or TALER_EC_GENERIC_PARAMETER_MALFORMED.

404 Not found:

The challenger service is unaware of a matching client. or the credentials of the client are invalid. Usually returned with TALER_EC_CHALLENGER_GENERIC_CLIENT_UNKNOWN.

500 Internal server error:

The challenger service encountered an internal error. Usually returned with TALER_EC_GENERIC_DB_FETCH_FAILED or TALER_EC_GENERIC_DB_STORE_FAILED or TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE.

Details::

interface ChallengeSetupRequest {
  // If true, the given address should not be edited.
  // Defaults to 'false' if not specified.
  read_only?: boolean;

  // Optional, additional fields to pre-populate
  // the address to be validated.
  // The fields depend on the challenger type.
  [x: string]: any;
}

interface ChallengeSetupResponse {
  // Nonce to use when constructing /authorize endpoint.
  nonce: string;
}