VivoKey Scan API

V2021.01

Definitions

Some transponder industry terms are built around the concept of "card" technology. Modern passively coupled chip technology has moved well beyond the card form factor, but within the context of this document, consider the term "card" to mean the passive transponder device.

API Keys

We use API keys to help secure calls to critical endpoints. To get an API key, you must create a developer account at https://developer.vivokey.com then create your keys. Keys are displayed only once, so it is important you document your key immediately after it is generated.

Member ID

All claimed VivoKey implants associated with an active VivoKey member profile will return a Member ID with a successful call to check-result. A Member ID is a hash value of the person’s VivoKey ID (which is a VivoKey internal identifier), a secret salt value, and your developer account ID. This means any API key generated under your developer account will return the same Member ID for the same person, even if they have multiple chip implants associated with their VivoKey member profile. However the Member ID for this person will not be the same for other developers. This protects VivoKey members against unintended data collection or privacy invasion by comparing or matching Member IDs across different services. Sharing of Member IDs, API keys, or developer accounts across multiple organizations is not allowed.

Chip ID

The Chip ID for a VivoKey implant is only returned by a successful call to check-result if your developer account is properly licensed to verify authenticity of VivoKey chip implants directly. Like Member ID, Chip IDs are a hash value of the chip’s internal identifier, a secret salt value, and your developer account ID. Sharing of Chip IDs, API keys, or developer accounts across multiple organizations is not allowed.

Endpoints

get-challenge

Obtains a temporary cryptographic picc-challenge from the server. The intention is to obtain this challenge before any chip scan event occurs so the PCD is ready to initiate the cryptographic process and quickly deliver the challenge to the PICC, rather than a chip scan event starting and then having to initiate an http request to get a challenge.

Accepts json dictionary containing the following

name length description
api-key 60 The hex encoded 30 byte API key issued via developer account

Example get-challenge request

{
"api-key": "3dd9f2c8bd13e803cbc599cf32875c9d9fbf854dc419d9a79c517e98c21a"
}

Returns json dictionary containing the following

name length description
picc-challenge 32 A 16 byte hex encoded string PICC challenge. Use of all 16 bytes may not be necessary depending on PICC type and expected challenge. LSBs may be truncated to required challenge length.
timeout int Integer value equal to the number of seconds the PICC challenge is valid. After timeout, a call to /check-response will fail regardless.

Example get-challenge response

{
"picc-challenge": "17695fd27eaf8c65833d50cbff12a501",
"timeout": 30
}            

pcd-challenge

For certain chips which only support mutual authentication (Spark 2), the chip will send a challenge to the PCD first. In this scenario we must conduct a call to pcd-challenge during a chip scan event so the backend can process the challenge issued by PICC to the PCD.

Accepts json dictionary containing the following

name length description
picc-uid 20 PICC uid represented in hexadecimal notation, all capital letters, no separators. Ex. 0428375BFA44D7 for a 7 byte UID (Spark 2).
picc-challenge 32 The full hex string challenge from /get-challenge (PICC challenge)
pcd-challenge 32 The hex encoded PCD challenge string issued from PICC

Example pcd-challenge request

{
"picc-uid": "04F2DA739E2BA0",
"picc-challenge": "17695fd27eaf8c65833d50cbff12a501",
"pcd-challenge": "55ecc39e823fd6c7c244f0d14a127f28"
}            

Returns json dictionary containing the following

name length description
pcd-response 64 The full hex encoded PCD response string to send back to PICC.

Example pcd-challenge response

{
"pcd-response": "358dcaf0dfdd7ffa15c74e0ef2eeaa9be376d2ad7d20868c8079a2f545b00522"
}            

check-response

The server will process the PICC challenge response to check authenticity. If the PICC challenge and PICC response match, the chip scan event will be considered a success and the authenticity of the chip will be validated. If this occurs, the PICC association will be checked to ensure it is associated with an active VivoKey profile. If so, an ID will be returned.

Accepts json dictionary containing the following

name length description
picc-uid 20 PICC uid represented in hexadecimal notation, all capital letters, no separators. Ex. 0428375BFA44D7 for a 7 byte UID (Spark 2).
picc-challenge 32 The full hex string challenge from /get-challenge (PICC challenge)
picc-response 32 The hex encoded PICC response to PICC challenge*
Warning *Some products only process 10 bytes of a challenge. In those cases the picc-challenge must truncate LSBs to shorten to a length of 10 and append any required flags before sending to the product for processing. For example, the picc-challenge "qcjNbPbcyOCLL3Fc" is passed as "qcjNbPbcyO" to these products. However, the full picc-challenge is always used when calling the API.

Example check-response request (if product processes 16 byte challenge/response)

{
"picc-uid": "04F2DA739E2BA0",
"picc-challenge": "741f849e6650d4d97445ca1384856fd9",
"picc-response": "e79b8d9fbbac5cdb484b4851c743c1c530b623483021e16f11e19cf2c71691b3"
}         

Returns json dictionary containing the following

name length description
check-result 11 Simple human readable response code (table 1)
result-data 128 Relevant data returned from check result (table 1)

Table 1. Possible check-result codes

check-result meaning result-data
error Error codes are non-specific. This is to ensure no unintentional state or status data related to the chip scan event is unintentionally leaked. <empty>
member-id Indicates success, and result-data will contain the 64 byte unique Member ID of the VivoKey member. Unique 64 byte hex encoded member ID
chip-id Indicates success, and result-data will contain the 64 byte unique Chip ID of the VivoKey chip. Unique 64 byte hex encoded chip ID
chip-member Indicates success, and result-data will be an array consisting of the 64 byte unique Chip ID, then the 64 byte unique Member ID [chip-id, member-id]

Example check-result response returns 64 byte hex encoded Member ID

{
"check-result": "member-id",
"result-data": "75e95abb37ee6e413ce5431f3785023312093c7fb62deb77dbe4c34a3a108227ae28e61998029c3edbc6393f84e0422315dc4c87e10fe31db4a435790f051579"
}         

Example check-result response returns chip-member response with two IDs; the Chip ID of the scanned chip and the Member ID the of the VivoKey member the chip is associated with

{
"check-result": "chip-member",
"result-data": [ "1b3e4b680990ba50cb94687868f435a2dedd82af0fc2063a35daeb467c3a276afc57faacb9b59a3099e2ec0d63aa9d353373f3dc811bceaf313400fad84cf06b",	
"75e95abb37ee6e413ce5431f3785023312093c7fb62deb77dbe4c34a3a108227ae28e61998029c3edbc6393f84e0422315dc4c87e10fe31db4a435790f051579"
]
}

Mobile App Security

The developer’s mobile application must employ its own API security measures to secure the API key or keys, and communication between the mobile app and application servers. You should definitely explore technologies like certificate pinning to trust your server connections, Keystore for Android, and Keychain for iOS to enable trusted storage of your mobile app data. You should also explore Mobile App Attestation techniques like SafetyNet for Android and DeviceCheck for iOS to ensure your servers can trust your app is making API requests.

Chip Scan Event Flow

Below is an example of chip scan event flow to obtain Member ID using a Spark 1 implant. The approach uses an application server to proxy the get-challenge call to shield the api key and keep it from being coded into your application. It is not recommended that your API keys be deployed in source code to your mobile app as they would be vulnerable to decompiling. There are other means you can use to protect your api key, this is just one example.

Chip Scan NFC Flow

The NFC command flow for a chip scan event will depend on the type of PICC being presented to the PCD. The following diagram depicts the flows for various VivoKey products.

NFC Commands

The actual commands used to send and receive data from VivoKey chip implants over NFC will depend on the operating system and NFC framework of the PCD hardware, as well as the VivoKey product being scanned. This section will be expanded in the next version of this document to include code examples for various operating systems. At this time we recommend developers attempt to utilize our easily integrated development libraries for Android and iOS.


©2021 VivoKey Technologies Inc. VivoKey Accounts Counter DCCCXXXIX