get-private-otp-devices-DEVICE_ID.rst (2978B)
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`` 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:`404 Not found`: 25 The OTP device or instance is unknown to the backend. 26 27 **Details:** 28 29 .. ts:def:: OtpDeviceDetails 30 31 interface OtpDeviceDetails { 32 33 // Human-readable description for the device. 34 device_description: string; 35 36 // Algorithm for computing the POS confirmation. 37 // 38 // Currently, the following numbers are defined: 39 // 0: None 40 // 1: TOTP without price 41 // 2: TOTP with price 42 otp_algorithm: Integer; 43 44 // Counter for counter-based OTP devices. 45 otp_ctr?: Integer; 46 47 // Current time for time-based OTP devices. 48 // Will match the ``faketime`` argument of the 49 // query if one was present, otherwise the current 50 // time at the backend. 51 // 52 // Available since protocol **v10**. 53 otp_timestamp: Integer; 54 55 // Current OTP confirmation string of the device. 56 // Matches exactly the string that would be returned 57 // as part of a payment confirmation for the given 58 // amount and time (so may contain multiple OTP codes). 59 // 60 // If the ``otp_algorithm`` is time-based, the code is 61 // returned for the current time, or for the ``faketime`` 62 // if a TIMESTAMP query argument was provided by the client. 63 // 64 // When using OTP with counters, the counter is **NOT** 65 // increased merely because this endpoint created 66 // an OTP code (this is a GET request, after all!). 67 // 68 // If the ``otp_algorithm`` requires an amount, the 69 // ``amount`` argument must be specified in the 70 // query, otherwise the ``otp_code`` is not 71 // generated. 72 // 73 // This field is *optional* in the response, as it is 74 // only provided if we could compute it based on the 75 // ``otp_algorithm`` and matching client query arguments. 76 // 77 // Available since protocol **v10**. 78 otp_code?: string; 79 80 }