Contents

GET /authorize/$NONCE#
POST /authorize/$NONCE#

This is the “authorization” endpoint of the OAuth 2.0 protocol. This endpoint is used by the user-agent. It will return a form to enter the address.

The NONCE is a unique value identifying the challenge, should be shown to the user so that they can recognize it when they receive the TAN code.

Note that both for GET and POST requests the request arguments must be given in the URL and the body should be empty. We currently do NOT support using x-www-form-urlencoded arguments in the body, even for a POST.

Request:

Query Parameters:

  • response_type – Must be code

  • client_id – Identifier of the client.

  • redirect_uri – URI-encoded redirection URI to use upon authorization.

  • state – Arbitrary client state to associate with the request.

  • scope – Not supported, any value is accepted.

  • code_challenge – A string to enhance security using PKCE (available since v3).

  • code_challenge_method – The method used for the code_challenge. Options are S256 (SHA-256) or plain (available since v3).

Response:

200 OK:

The the response is a ChallengeStatus. Since protocol v1.

302 Found:

Returned when the client explicitly accepts text/html returning a redirection to the WebUI. Since protocol v1.

400 Bad Request:

The request does not follow the spec. The response will include error code, hint and detail. 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.

406 Not Acceptable:

The client ask for “text/html” and the backend installation does not include the required HTML templates.

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.

interface ChallengeStatus {

  // indicates if the given address cannot be changed anymore, the
  // form should be read-only if set to true.
  fix_address: boolean;

  // form values from the previous submission if available, details depend
  // on the ADDRESS_TYPE, should be used to pre-populate the form
  last_address?: Object;

  // is the challenge already solved?
  solved: boolean;

  // number of times the address can still be changed, may or may not be
  // shown to the user
  changes_left: Integer;

  // when we would re-transmit the challenge the next
  // time (at the earliest) if requested by the user
  // only present if challenge already created
  // @since **v2**
  retransmission_time: Timestamp;

  // how many times might the PIN still be retransmitted
  // only present if challenge already created
  // @since **v2**
  pin_transmissions_left: Integer;

  // how many times might the user still try entering the PIN code
  // only present if challenge already created
  // @since **v2**
  auth_attempts_left: Integer;
}
Contents