TOTP tokens for EVV

We suggest using TOTP hardware tokens for Electronic Visit Verification (EVV). Protectimus EVV solution based on the TOTP algorithm allows identifying the exact time of visits using one-time passwords from TOTP tokens.

TOTP tokens for Electronic Visit Verification (EVV) are a super easy and effective EVV method both for homecare personnel and people receiving help at home.

Hardware TOTP tokens for EVV look like keyfobs and don’t require installation, internet connection, or electricity to work. It’s enough to give the TOTP token device to the care receiver and ask the homecare worker to write down one-time codes from the EVV TOTP token at the beginning and the end of their visits. Then the one-time codes are transferred to the Protectimus EVV solution via API, and Protectimus returns the precise time when every OTP code was generated.

This guide shows how to integrate the Protectimus EVV solution with your Electronic Visit Verification system.

1. How the Protectimus TOTP Tokens Work for Electronic Visit Verification (EVV)

The Time-Based One-Time Password generation algorithm (TOTP) allows us to calculate the time when every one-time code was generated with an accuracy of 30 or 60 seconds, depending on the type of TOTP token you choose. We highly recommend using TOTP tokens with 60 second time step for EVV because of the problem of matching OTPs that occurs with 30-second time step tokens. We’ll describe this issue in detail below.

The TOTP algorithm for EVV works like this:

• The patient gets the hardware TOTP token. The EVV TOTP token has a built-in clock and a unique pre-programmed shared secret.
• The same shared secret is known to the Protectimusr EVV system, which verifies the one-time passwords and calculates the time when these OTPs were generated.

So the scenario of using Protectimus TOTP tokens for Electronic Visit Verification (EVV) looks like this:

1. The caregiver visits the patient and writes down two one-time passwords from the OTP token: before and after the visit.
2. Then the caregiver enters these one-time codes into the Electronic Visit Verification System to confirm they conducted the visit.
3. The Electronic Visit Verification System turns to the Protectimus EVV server to calculate the time of the visit.
4. Knowing the shared secret, the Protectimusr EVV server generates one-time passwords for the previous day/week/month and calculates the time of generation of certain OTPs. This way, we find out when the caregiver visited the patient.

2. The Problem of Coinciding One-Time Passwords in EVV

PLEASE NOTE! We recommend 8-digit TOTP tokens with 60 seconds time steps for Electronic Visit Verification (EVV).

There is a limit to the number of combinations consisting of 6 digits. And this limit is not very large.

Over a long period (a week or a month), the numeric values of one-time passwords will inevitably repeat. Two one-time passwords generated at different times will match. It may complicate the recognition of the exact time of OTP generation.

To reduce this problem, it is better to use TOTP tokens with a larger number of characters and larger time intervals. We recommend 8-digit TOTP tokens with 60 seconds time steps for Electronic Visit Verification (EVV).

3. How to Integrate Protectimus EVV with Your Electronic Visit Verification System

3.1. Get Registered and Add Tokens to the Protectimus Cloud Service or On-Prem Platform

1. Register with the Protectimus Cloud Service and activate API or install the Protectimus On-Premise Platform.
2. Add Tokens. To do this, log into your account in Protectimus SAAS Service or On-Premise Platform and go to the Tokens page.

 

3. Click the Add Token button.

 

4. Select the Token Protectimus Two

 

5. Upload the file that will be sent to you after you order the TOTP tokens for EVV.

3.2. Use Protectimus API to Integrate Protectimus with Your Electronic Visit Verification System

PLEASE NOTE! You can use our Postman Collection for quicker integration. A Postman Collection is available upon request. Please, contact our support team.

Protectimus API’s design is based on the REST principles. Data is transmitted in the XML format or the JSON format. Parameter values are identical in these formats. By default, responses are transmitted in the XML format.

Detailed API Integration Instructions are available here.

3.2.1. Authorization

The Protectimus API is only accessible to authorized users. Our solution uses Basic authentication. The login (username) of the administrator that submits a request is used as the username, and an authentication token is used as the password.

An authentication token is the hash of a string that consists of the following elements:

<ApiKey>:<YYYYMMDD>:<HH>

Where:

• ApiKey is an API key, which is unique for each administrator; it is provided and may be changed on the profile management page https://service.protectimus.com/profile
• YYYYMMDD is the current date in the specified format
• НН is the UTC time in the HH format (only hours in the 24-hour format, without minutes or seconds)

Example:

The administrator’s profile contains the following information: 
ApiKey – MySecureApiKey; Date - 30 January 2014; Time - 17:42 (UTC).

String for hash: MySecureApiKey:20140130:17

Hash SHA256 for this text: 62704fb3a9dcf7b5b3cf7bda6ac9d0b0aa37c6fce8d0fae6b466c91ba68894f5

3.2.2. Request Submission

The protocol for transmitting all requests to the Protectimus API is HTTPS.

Request Format:

<НТТР-method>
https://service.protectimus.com/multipass-web-api/v<API_version>/<API_section>/<API_method>.<respo
nse_format>

The parameters specified above have the following values:

• НТТР-method is the method typical for the current request.
• API_version is the API version that you want to use. Currently, only the first version is available; therefore, this part of the request will look like this: “v1”.
• API_section is the section to which the method you are calling belongs. The following sections are available: auth-service, resource-service, token-service, and user-service. The API methods’ descriptions are divided into the sections to which these methods belong.
• API_method is the method you are calling.
• response_format is the format in which you want to receive a response: XML or JSON. By default, XML is the selected format.

If an error occurs, the processing of a request is terminated, and an error message is returned. A list of errors and descriptions of errors are given in the Error Message section of the Protectimus API Integration Instructions.

3.2.3. Protectimus EVV API Method

Use this API Method to get the time when the one-time password was generated.

Option 1. CURL

curl --request POST 'https://api.protectimus.com/api/v1/token-service/otp-time' \

--header 'Authorization: Basic ZGFueWxvLmRlaW5la29AZ21haWwuY29tOmNTI=' \

--header 'Content-Type: application/x-www-form-urlencoded' \



--data-urlencode 'tokenId=123' \

--data-urlencode 'otp=825043'

Option 2. HTTP

POST /api/v1/token-service/otp-time HTTP/1.1
Host: api.protectimus.com
Authorization: Basic ZGFueWxvLmRlaW5la29AZ21haWwuY29tOmNTI=
Content-Type: application/x-www-form-urlencoded
Content-Length: 22


tokenId=123&otp=825043

If you have any questions, please, contact Protectimus customer support service.