get-private-otp-devices-DEVICE_ID.rst (3730B)
1 .. http:get:: [/instances/$INSTANCE]/private/otp-devices/$DEVICE_ID 2 3 This is used to obtain detailed information about a specific OTP device. 4 5 The client can provide additional inputs in the query to allow the backend 6 to compute and return a sample OTP code. Note that it is not an error if 7 the client provides query arguments that are not being used *or* that are 8 insufficient for the server to compute the ``otp_code``: If the client 9 provides inadequate query parameters, the ``otp_code`` is simply omitted 10 from the response. 11 12 **Required permission:** ``otp-devices-read`` (see :ref:`Scopes <merchant-api-scopes>`) 13 14 **Query:** 15 16 :query faketime=TIMESTAMP: *Optional*. Timestamp in seconds to use when calculating the current OTP code of the device. Since protocol **v10**. 17 :query price=AMOUNT: *Optional*. Price to use when calculating the current OTP code of the device. Since protocol **v10**. 18 19 **Response:** 20 21 :http:statuscode:`200 OK`: 22 The backend has successfully returned the detailed information about a specific OTP device. 23 Returns a `OtpDeviceDetails`. 24 :http:statuscode:`401 Unauthorized`: 25 The request is unauthorized. 26 :http:statuscode:`404 Not found`: 27 The OTP device or instance is unknown to the backend. 28 Returned with ``TALER_EC_MERCHANT_GENERIC_OTP_DEVICE_UNKNOWN``. 29 :http:statuscode:`500 Internal Server Error`: 30 The server experienced an internal failure. 31 Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``. 32 33 **Details:** 34 35 .. ts:def:: OtpDeviceDetails 36 37 interface OtpDeviceDetails { 38 39 // Human-readable description for the device. 40 device_description: string; 41 42 // Algorithm for computing the POS confirmation. 43 // 44 // Currently, the following numbers are defined: 45 // 0: None 46 // 1: TOTP without price 47 // 2: TOTP with price 48 // 3: ECDSA signature over the order's challenge 49 // (since protocol **vChallengeConfirmation**) 50 // 4: EdDSA signature over the order's challenge 51 // (since protocol **vChallengeConfirmation**) 52 otp_algorithm: Integer; 53 54 // Public key of the device key pair, only present for 55 // challenge-signature algorithms (3 and 4). 56 // Since protocol **vChallengeConfirmation**. 57 otp_device_pub?: string; 58 59 // Counter for counter-based OTP devices. 60 otp_ctr?: Integer; 61 62 // Current time for time-based OTP devices. 63 // Will match the ``faketime`` argument of the 64 // query if one was present, otherwise the current 65 // time at the backend. 66 // 67 // Available since protocol **v10**. 68 otp_timestamp: Integer; 69 70 // Current OTP confirmation string of the device. 71 // Matches exactly the string that would be returned 72 // as part of a payment confirmation for the given 73 // amount and time (so may contain multiple OTP codes). 74 // 75 // If the ``otp_algorithm`` is time-based, the code is 76 // returned for the current time, or for the ``faketime`` 77 // if a TIMESTAMP query argument was provided by the client. 78 // 79 // When using OTP with counters, the counter is **NOT** 80 // increased merely because this endpoint created 81 // an OTP code (this is a GET request, after all!). 82 // 83 // If the ``otp_algorithm`` requires an amount, the 84 // ``amount`` argument must be specified in the 85 // query, otherwise the ``otp_code`` is not 86 // generated. 87 // 88 // This field is *optional* in the response, as it is 89 // only provided if we could compute it based on the 90 // ``otp_algorithm`` and matching client query arguments. 91 // 92 // Available since protocol **v10**. 93 otp_code?: string; 94 95 }