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:

• Open ID Connect IdP - An OAuth2 + OpenID Connect implementation enabling member authentication and identity data such as name, email, etc. so VivoKey community members can authenticate and identify themselves to "Relying Party" websites, services, or apps just by tapping their VivoKey implant.
• Validation API - Issue validation challenges via the Validation API to confirm potentially sensitive actions such as selling or transferring cryptocurrency, changing profile or security settings, etc. To approve or validate the request, the VivoKey community member must tap their VivoKey to securely confirm the action.

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:

• openid - OpenID scope is required to indicate intent to use OIDC
• profile - the member's full name (unverified)
• email - the member's email address (unverified)

OIDC Endpoints

The following OIDC URLs are provided by VivoKey Connect:.

• Base - https://api.vivokey.com/openid/
• Discovery - https://api.vivokey.com/openid/.well-known/openid-configuration
• JWKS - https://api.vivokey.com/openid/jwks/
• Authorization - https://api.vivokey.com/openid/authorize/
• Token - https://api.vivokey.com/openid/token/
• ID Info - https://api.vivokey.com/openid/userinfo/

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.

• A VivoKey community member elects to log in to your site or app with their VivoKey by tapping a link or button, which may typically be described as "Log in with VivoKey"
• Your site constructs an OpenID Connect Authentication Request and redirects the browser to https://api.vivokey.com/openid/authorize/ with the authentication request parameters. These parameters include a list of requested scopes and a redirect URL.
• On the VivoKey site, the VivoKey member is prompted to authenticate with their VivoKey.
• The member is then presented with your site’s name, the list of requested claims, and a short description of each claim. The person is given the option to accept the information sharing and continue, or deny the sharing of this information.
• The browser is redirected to the Relying Party site with an authorization code.
• The Relying Party site constructs a token request using the authorization code and requests a token from https://api.vivokey.com/openid/token/. *Note that this happens server to server "behind the scenes" and does not involve the browser.
• The VivoKey OIDC server provides an OAuth2 Access Token and an OIDC ID Token.
• The Relying Party site can then, optionally, request identity information from https://api.vivokey.com/openid/userinfo/ using the ID Token.
• The Relying Party site can store and use the Access Token with the Validation API to confirm future behavior, including passwordless authentication, issue two-factor challenges, request activity confirmations, etc.

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:

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

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:

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:

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

• Accept: The member approves the challenge by tapping their VivoKey.
• Decline: The member specifically declines or rejects the challenge.
• Timeout: The member does nothing and the challenge times out.

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

* STRING? means optional value

Machine-readable error strings

• token-expired: The member’s Access Token has expired and should be renewed.
• declined: The member declined the authorization.
• timeout: The member did not tap to authorize within the given timeout period.