post-private-otp-devices.rst (3459B)
1 .. http:post:: [/instances/$INSTANCE]/private/otp-devices 2 3 This is used to associate an OTP device with an instance. 4 5 **Required permission:** ``otp-devices-write`` (see :ref:`Scopes <merchant-api-scopes>`) 6 7 **Request:** 8 9 The request must be a `OtpDeviceAddDetails`. 10 11 **Response:** 12 13 :http:statuscode:`204 No content`: 14 The creation of the template is successful. 15 :http:statuscode:`200 OK`: 16 The device was created and uses a challenge-signature 17 ``otp_algorithm`` ("ECDSA_CHALLENGE" or "EDDSA_CHALLENGE"): the 18 backend generated the device key pair and returns a 19 `OtpDeviceCreateResponse` with the public key. 20 Since protocol **vChallengeConfirmation**. 21 :http:statuscode:`400 Bad Request`: 22 The request body is malformed. 23 :http:statuscode:`404 Not found`: 24 The merchant instance is unknown or it is not in our data. 25 :http:statuscode:`409 Conflict`: 26 An OTP device with this ID already exists with different details. 27 Returned with ``TALER_EC_MERCHANT_PRIVATE_POST_OTP_DEVICES_CONFLICT_OTP_DEVICE_EXISTS``. 28 :http:statuscode:`413 Request entity too large`: 29 The uploaded body is to long, it exceeds the size limit. 30 Returned with an error code of 31 ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``. 32 :http:statuscode:`500 Internal Server Error`: 33 The server experienced an internal failure. 34 Returned with ``TALER_EC_GENERIC_DB_START_FAILED``, 35 ``TALER_EC_GENERIC_DB_FETCH_FAILED``, 36 ``TALER_EC_GENERIC_DB_SOFT_FAILURE`` or 37 ``TALER_EC_GENERIC_DB_COMMIT_FAILED``. 38 39 **Details:** 40 41 .. ts:def:: OtpDeviceAddDetails 42 43 interface OtpDeviceAddDetails { 44 45 // Device ID to use. 46 otp_device_id: Slug; 47 48 // Human-readable description for the device. 49 otp_device_description: string; 50 51 // A key encoded with RFC 3548 Base32. 52 // IMPORTANT: This is not using the typical 53 // Taler base32-crockford encoding. 54 // Instead it uses the RFC 3548 encoding to 55 // be compatible with the TOTP standard. 56 // Since protocol **vChallengeConfirmation** this field is optional: 57 // it MUST be omitted for the challenge-signature algorithms 58 // (3 and 4), where the backend generates the key pair itself 59 // and never exposes the private key. 60 otp_key?: string; 61 62 // Algorithm for computing the POS confirmation. 63 // "NONE" or 0: No algorithm (no pos confirmation will be generated) 64 // "TOTP_WITHOUT_PRICE" or 1: Without amounts (typical OTP device) 65 // "TOTP_WITH_PRICE" or 2: With amounts (special-purpose OTP device) 66 // "ECDSA_CHALLENGE" or 3: ECDSA signature over the order's 67 // challenge, since protocol **vChallengeConfirmation**. 68 // "EDDSA_CHALLENGE" or 4: EdDSA signature over the order's 69 // challenge, since protocol **vChallengeConfirmation**. 70 // The "string" variants are supported @since protocol **v7**. 71 otp_algorithm: Integer | string; 72 73 // Counter for counter-based OTP devices. 74 otp_ctr?: Integer; 75 } 76 77 .. ts:def:: OtpDeviceCreateResponse 78 79 interface OtpDeviceCreateResponse { 80 81 // Public key of the key pair generated by the backend for 82 // this device, to be configured into the offline verifier. 83 // For "ECDSA_CHALLENGE" a compressed NIST P-256 point, for 84 // "EDDSA_CHALLENGE" an Ed25519 public key. 85 // Crockford Base32 encoded. 86 // Since protocol **vChallengeConfirmation**. 87 otp_device_pub: string; 88 }