OpenID Connect API

Summary

VivoKey Connect APIs provide a number of interfaces 3rd party integrators can use to invite VivoKey community members to utilize their cryptobionic security implants with their applications and services.

Introduction

VivoKey Connect provides a number of APIs, including identity provider (IdP) interfaces that tie web standardized authentication and identity service protocols to our cryptobionic implantable subdermal transponders. Developers wishing to integrate VivoKey cryptobionic authentication, identification, and intent validation into cloud services, cryptocurrency exchange transactions, web portals, financial services, mobile apps, etc. will be able to enable cryptosecure, password-free experiences. VivoKey community members will be able to identify and authenticate themselves, as well as authorize sensitive activities and intents by simply tapping their VivoKey.

Currently, VivoKey Connect exposes two APIs:


OpenID Connect Identity Provider (IdP) API

VivoKey Connect's implemenation of OpenID Connect (OIDC) API provides an OAuth2 based OpenID Connect flow, enabling secure authentication while also allowing third-party sites ("Relying Party" in OpenID terminology) to request specific information ("claims") from the VivoKey community member. The OIDC API provides the following scopes and claims:

OIDC Endpoints

The following OIDC URLs are provided by VivoKey Connect:.

OIDC Client ID & Secret

To use VivoKey Connect OIDC endpoints, you will need a client ID and client secret that identify your application to the OIDC API. These credentials are issued by creating a custom application in the Advanced section of Profile Settings within the VivoKey smartphone app. Organizations that wish to present custom branded OIDC experiences to VivoKey community members can contact us to become an integration partner.

When you have completed creating a new application you will be assigned a client ID and secret, and can begin using the API.

Example authentication flow with OIDC

An example flow using OpenID Connect with a web-based Relying Party is as follows.


The VivoKey Validation API

Once you have a valid access token for the VivoKey member, you may use the Validation API to ask that member to confirm specific actions. We call this type of request a "validation challenge". For example, if a VivoKey member using your site or service wishes to update their personal information, change security details, or commit transactions, you may wish they authorize these actions by tapping their VivoKey. You can do this by issuing a "validation challenge" via the Validation API.

How it works

When you want to confirm any action, your server will post a validation challenge to the Validation API endpoint. VivoKey notifies the member via push notifications sent to any registered phones or devices. The member then uses one of those devices to scan their VivoKey, or decline the challenge. VivoKey servers then post back to your server with the result - success (member scanned their secure implant), declined (member explicitly rejected the challenge), or timed out (member did not scan and did not reject). Your site should then take appropriate action based on the result.

Initiating a validation challenge

To start the validation challenge process, craft a post request to https://api.vivokey.com/v1.0/validate

Your request must include an Authorization: Bearer header containing the member's Access Token. For example, if the Access Token you received is fdd3b2f5ef1f35ecb5317da0068bdef0, then your post request should include the following header line:

Authorization: Bearer fdd3b2f5ef1f35ecb5317da0068bdef0

Your request body must be a JSON dictionary containing the following keys:

name length description
message 60 A string indicating what the authorization request is for. This will be shown to the VivoKey member.
id 256 A unique, randomized UTF-8 encoded string that uniquely identifies this specific request. This ID will be passed back to you by the VivoKey server upon callback.
timeout 30~86400 An integer indicating the number of seconds that this authorization request is valid for. If you don’t supply a timeout, the default value of 60 will be used. Minimum timeout is 30, maximum is 86400 (24 hours).
callback ?? A URL which VivoKey will call back to with success or failure results. This URL must be one of the URLs supplied previously; see above.

For example, to authorize a payment, you might provide a dictionary which looks like the following:

{
   “message”: “Buy VPN access (1 year) for $49.50”,
   “id”: “7aff437371272981c56dcf62a2e98fcd”,
   “timeout”: 60,
   “callback”: “https://secure.vpn.website/vivokey-auth-response/”
}

If the HTTP POST request was accepted, our server will respond with a JSON dictionary containing the following keys and values:

name length description
accepted STRING true
vivo_id STRING A value representing VivoKey’s unique identifier for this specific API request (this is unrelated to the ID or Access Token).

Successful acceptance of the request at this point means that your validation challenge has been accepted and passed on to the VivoKey member, it does not mean that the person has tapped their VivoKey.

If the HTTP POST request was not accepted, the JSON dictionary will contain the following keys and values:

name length description
accepted STRING false
message STRING A human-readable message explaining the problem.
error STRING A machine-readable string containing the error message

Assuming the POST request was accepted, there are now three things which can happen:

The VivoKey server will make a request to your "callback" endpoint URL with a JSON dictionary. This dictionary will contain the following keys:

name length description
success STRING true or false
message STRING? A human-readable error message (only present if success is false)
error STRING? A machine-readable error string (only present if success is false)
vivo_id STRING Our internal ID which was given in response to the initial API request
id STRING The unique request ID yuor server submitted to our API for this request

* STRING? means optional value

Machine-readable error strings


©2021 VivoKey Technologies Inc. VivoKey Accounts Counter MLXXXIV