Contents

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 Authorization header is mandatory and must be of the form Bearer secret-token:$CLIENT_SECRET: the value is expected to carry the RFC 8959 secret-token: prefix, and the prefix is part of the secret as stored by challenger-admin. The Bearer scheme token is matched case-insensitively.

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.

The body is optional: a request with no body at all, or with a body of length zero, is accepted and leaves the address unset. If a body is present it must be a JSON object; any other JSON value is rejected.

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. Error codes used are:

  • TALER_EC_GENERIC_PARAMETER_MALFORMED — the $CLIENT_ID in the URL is not a number (detail is "client_id"), the body is valid JSON but not an object (detail is "address"), or read_only is present in the body but is not a boolean (detail is "read_only").

  • TALER_EC_GENERIC_JSON_INVALID — the body is not well-formed JSON.

403 Forbidden:

The client did not present usable credentials. Since protocol v8; previously reported as 400. In both cases detail is "Authorization". Error codes used are:

  • TALER_EC_GENERIC_PARAMETER_MISSING — there is no Authorization header at all.

  • TALER_EC_GENERIC_PARAMETER_MALFORMED — the header is present but does not use the Bearer scheme, or its value lacks the RFC 8959 secret-token: prefix.

404 Not found:

The challenger service is unaware of a matching client, or the credentials of the client are invalid. These two cases are deliberately not distinguished. Always returned with TALER_EC_CHALLENGER_GENERIC_CLIENT_UNKNOWN.

405 Method Not Allowed:

The request used a method other than POST or OPTIONS. Returned by the request router with an Allow header and an empty body; in particular there is no Taler error code.

500 Internal server error:

The challenger service encountered an internal error. Error codes used are:

  • TALER_EC_GENERIC_DB_STORE_FAILED — the database transaction that authenticates the client and inserts the validation failed, either hard or by exhausting the retries for serialization failures (detail is "do_insert_validation").

  • TALER_EC_GENERIC_PARSER_OUT_OF_MEMORY — the service ran out of memory while buffering the request body.

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;

  // Time when this validation process expires.  After this time it can
  // no longer be authorized or exchanged for a token.
  // Available since protocol v9.
  expires: Timestamp;
}
Contents