get-private-otp-devices-DEVICE_ID.rst (3270B)
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:`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 otp_algorithm: Integer; 49 50 // Counter for counter-based OTP devices. 51 otp_ctr?: Integer; 52 53 // Current time for time-based OTP devices. 54 // Will match the ``faketime`` argument of the 55 // query if one was present, otherwise the current 56 // time at the backend. 57 // 58 // Available since protocol **v10**. 59 otp_timestamp: Integer; 60 61 // Current OTP confirmation string of the device. 62 // Matches exactly the string that would be returned 63 // as part of a payment confirmation for the given 64 // amount and time (so may contain multiple OTP codes). 65 // 66 // If the ``otp_algorithm`` is time-based, the code is 67 // returned for the current time, or for the ``faketime`` 68 // if a TIMESTAMP query argument was provided by the client. 69 // 70 // When using OTP with counters, the counter is **NOT** 71 // increased merely because this endpoint created 72 // an OTP code (this is a GET request, after all!). 73 // 74 // If the ``otp_algorithm`` requires an amount, the 75 // ``amount`` argument must be specified in the 76 // query, otherwise the ``otp_code`` is not 77 // generated. 78 // 79 // This field is *optional* in the response, as it is 80 // only provided if we could compute it based on the 81 // ``otp_algorithm`` and matching client query arguments. 82 // 83 // Available since protocol **v10**. 84 otp_code?: string; 85 86 }