POST [/instances/$INSTANCE]/private/otp-devices

This is used to associate an OTP device with an instance.

Required permission: otp-devices-write

Request:

The request must be a OtpDeviceAddDetails.

Response:

204 No content:

The creation of the template is successful.

200 OK:

The device was created and uses a challenge-signature otp_algorithm (“ECDSA_CHALLENGE” or “EDDSA_CHALLENGE”): the backend generated the device key pair and returns a OtpDeviceCreateResponse with the public key. Since protocol vOpenSesame.

400 Bad Request:

The request body is malformed.

404 Not found:

The merchant instance is unknown or it is not in our data.

409 Conflict:

An OTP device with this ID already exists with different details. Returned with TALER_EC_MERCHANT_PRIVATE_POST_OTP_DEVICES_CONFLICT_OTP_DEVICE_EXISTS.

413 Request entity too large:

The uploaded body is to long, it exceeds the size limit. Returned with an error code of TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT.

500 Internal Server Error:

The server experienced an internal failure. Returned with TALER_EC_GENERIC_DB_START_FAILED, TALER_EC_GENERIC_DB_FETCH_FAILED, TALER_EC_GENERIC_DB_SOFT_FAILURE or TALER_EC_GENERIC_DB_COMMIT_FAILED.

Details:

interface OtpDeviceAddDetails {

  // Device ID to use.
  otp_device_id: string;

  // Human-readable description for the device.
  otp_device_description: string;

  // A key encoded with RFC 3548 Base32.
  // IMPORTANT: This is not using the typical
  // Taler base32-crockford encoding.
  // Instead it uses the RFC 3548 encoding to
  // be compatible with the TOTP standard.
  // Since protocol **vOpenSesame** this field is optional:
  // it MUST be omitted for the challenge-signature algorithms
  // (3 and 4), where the backend generates the key pair itself
  // and never exposes the private key.
  otp_key?: string;

  // Algorithm for computing the POS confirmation.
  // "NONE" or 0: No algorithm (no pos confirmation will be generated)
  // "TOTP_WITHOUT_PRICE" or 1: Without amounts (typical OTP device)
  // "TOTP_WITH_PRICE" or 2: With amounts (special-purpose OTP device)
  // "ECDSA_CHALLENGE" or 3: ECDSA signature over the order's
  //   challenge, since protocol **vOpenSesame**.
  // "EDDSA_CHALLENGE" or 4: EdDSA signature over the order's
  //   challenge, since protocol **vOpenSesame**.
  // The "string" variants are supported @since protocol **v7**.
  otp_algorithm: Integer | string;

  // Counter for counter-based OTP devices.
  otp_ctr?: Integer;
}

interface OtpDeviceCreateResponse {

  // Public key of the key pair generated by the backend for
  // this device, to be configured into the offline verifier.
  // For "ECDSA_CHALLENGE" a compressed NIST P-256 point, for
  // "EDDSA_CHALLENGE" an Ed25519 public key.
  // Crockford Base32 encoded.
  // Since protocol **vOpenSesame**.
  otp_device_pub: string;
}