VivoKey Key Value Store API

Introduction

The Key Value Store API is an extension to the Scan API that allows storage and recall of key-identified data associated with a particular VivoKey member or chip. This API was created to allow developers to store data relevant to partner applications, particularly legacy applications which may not be easily altered or applications unable to be altered at all due to policy or other issues. This can eliminate the need for building middleware services just to link small associated data elements between the VivoKey API and partner applications.

Basic functionality

The KVS API requires a successful chip scan authentication to be done using the Scan API. A successful authentication authorizes the storage and retrieval of data associated with the authenticated VivoKey member or VivoKey chip implant (depending on your API key configuration). The successfully authenticated PICC challenge issued by the Scan API will then be used as a temporary access token with the KVS API. Data will be stored and siloed in association with that member or chip only, and can only be updated or retrieved in the future using an authenticated PICC challenge from that member or chip.

For example, let’s say you have two users Bob and Alice. You then store key paired data for each using a key name of “age” and values of “35” for Bob and “27” for Alice, then the only way to retrieve Bob’s “age” value of “35” is by using a PICC challenge that has been successfully validated with Bob’s chip implant. This keeps data repositories unique to each VivoKey member or each VivoKey chip implant, depending on your API key configuration and licensing.

Data Security

The KVS API does not perform any application data encryption on your behalf. Data stored using this API is stored in whatever form you send it, so we require that you encrypt your data before storing it with KVS, and decrypt it after retrieval. Do not store sensitive data unencrypted on our servers. We assume no liability for any reason if your data is compromised.

Definitions

• KEY = the short 20 byte unique string to be used to identify the data
• VALUE = up to 256 bytes of data to be stored or recalled

Endpoints

• https://api2.vivokey.com/v1/kvp-store
  store data with specified keys
• https://api2.vivokey.com/v1/kvp-read
  recall data with specified keys

kvp-store

A json dictionary is sent containing key and value pairs to be stored in association with the VivoKey Member, or chip ID if the API key used is licensed and enabled for chip ID. Key stored data can be shared across similarly licensed API keys under your developer account, but not by API keys belonging to any other developer accounts. This allows for easy data sharing across different applications, each using different API keys (as they should).

Data can be read and overwritten by any API key under your developer account, so think carefully about key names. Subsequent calls to kvp-store for the same VivoKey member using the same key name by any API key under your developer account will overwrite the stored data under that key.

Accepts json dictionary containing the following

Example kvp-store request

{
   "challenge": "17695fd27eaf8c65833d50cbff12a501",
   "dict": [{"key": "patient-med-id",
            "value": "7713cdbc-2c6a-420b-b931-9c77b529fdce"},
            {"key" : "Other Data",
            "value": "this is some other relevant data"}]
}            

Returns json dictionary containing the following

Table 1. Possible result examples

The result will always be “success” or “error”. No further data will be provided.

Example kvp-store success response

{
   "result": "success"
}      

Example kvp-store error response (returns error because challenge is unvalidated)

{
   "result": "error"
}

kvp-read

Recalling stored data requires a validated PICC challenge and a key name. Any key name specified will always be returned, even if there is no stored data. Key names which are over length will be truncated to 20 bytes. If the PICC challenge is expired or invalid, a key name of “result” with a value of “error” will be returned.

Accepts json dictionary containing the following

Example kvp-read request which includes an alternate case "other DaTa"

{
   "challenge": "17695fd27eaf8c65833d50cbff12a501",
   "dict": ["patient-med-id", "Other Data", "other DaTa"]
}             

Returns json object containing the following

Example kvp-read response showing key case sensitivity and default empty return values

{
   “result”: “success”,
   “data”: {
      "patient-med-id": "7713cdbc-2c6a-420b-b931-9c77b529fdce",
      "Other Data": "this is some other relevant data",
      "other DaTa": ""
   }
}       

Example kvp-read response erroring because PICC challenge is expired (invalid). No specific error data will be provided.

{
   "result": "error"
}