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