Vivokey - API Development

  • Vivokey Technologies LLC
  • Monday, May 6, 2019
blog-image

Summary

The VivoKey Service is a platform providing various services and capabilities to VivoKey community members. This documentation describes VivoKey Service API support for OAuth2 authorization protocol, OpenID Connect identity provider (IdP) services, as well as the VivoKey Validation API endpoint.

Introduction

The VivoKey Service API provides a standards based identity provider (IdP) API, tying web standardized authentication and identity service protocols to 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.

The VivoKey Service exposes two APIs: ​ 1. Identity Provider (IdP) API - An OAuth2 + OpenID Connect implementation enabling member authentication and identity data such as name, email, etc. so VivoKey community members can log in to your website, service, or app just by tapping their VivoKey implant, rather than entering a password or using a cumbersome two-factor method.

  1. Validation API - You can issue validation challenges via the Validation API to confirm potentially sensitive actions such as selling or transferring cryptocurrency, changing profile or security settings, etc. The VivoKey community member must then tap their VivoKey to securely confirm the action.

API Credentials - Client ID & Secret

To use any VivoKey API endpoints, you will need a client ID and client secret that identify your application to the VivoKey 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 experiences to VivoKey community members can work with 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.

Identity Provider (IdP) API

The VivoKey IdP API provides an OpenID Connect flow, enabling secure login while also allowing third-party sites (“Relying Party” in OpenID terminology) to request specific information (‘claims’) from the community member. VivoKey IdP provides the following scopes and claims:

  • Profile scope (profile):
    • name: the person’s full name.
  • Email scope (email):
    • email: the person’s email address.

The following OpenID Connect URLs are provided by VivoKey:

Example authentication with the IdP API

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

  1. 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”
  2. 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 which must match that provided to VivoKey during creation of the custom application, the process through which you obtained your client ID and secret.
  3. On the VivoKey site, the person is prompted to log in with their VivoKey.
  4. The person 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 to log in, or deny the sharing of this information. Once the person has performed this action once for a given Relying Party, they are not asked again.
  5. The browser is redirected to the Relying Party site with an authorization code.
  6. 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.
  7. The VivoKey server provides an ID Token and Access Token.
  8. The Relying Party site can then, optionally, request identity information from https://api.vivokey.com/openid/userinfo/ using the ID Token.
  9. 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 an access token for the VivoKey member, you may then make use of the VivoKey Validation API to ask that member to confirm specific actions. We call this type of request a “validation challenge”. For example, if a person on your site wishes to update their personal information, change security details, or commit transactions, you may wish they authorize these actions by asking them to tap their VivoKey. You can do this by issuing a “challenge” via the Validation API.

Your server posts to the API endpoint, VivoKey notifies the member, the member scans their VivoKey or declines the challenge, then the VivoKey API posts back to your server with the result - success (member scanned their secure implant), declined (member explicitly rejected the challenge), or timed out.

Initiating a validation request

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:

  • description: A string indicating what the authorization request is for. This will be shown to the VivoKey member. The description will be preceded by the words “Scan your VivoKey to…” so make sure the description string makes sense. Maximum number of characters is 60.
  • id: 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. Maximum length of this ID string is 256 characters.
  • timeout: 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:

{

    “description”: “Buy VPN access (1 year) for $49.50”,

    “id”: “7aff437371272981c56dcf62a2e98fcd”,

    “timeout”: 120,

    “callback”: “https://secure.vpn.website/vivokey-auth-response/”

}

​If the post request was accepted, the server will respond with a JSON dictionary containing the following keys and values:

  • accepted: true
  • vivo_id: 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 post request was not accepted, the JSON dictionary will contain the following keys and values:

  • accepted: false
  • message: A human-readable message explaining the problem
  • error: A machine-readable string containing the error message

At this point, there are three things which can happen to the request:

  • Accept: The person can accept the request by tapping their VivoKey.
  • Decline: The person can specifically decline or reject the request.
  • Timeout: The request can time out without explicit action from the person.

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

  • success: true or false
  • message: a human-readable error message (only present if success is false)
  • error: a machine-readable error string (only present if success is false)
  • vivo_id: VivoKey’s internal ID, which will match the ID sent by VivoKey to your initial API request
  • id: the unique request ID submitted to our API for this request is returned to you

Machine-readable error strings

  • token-expired: The member’s Access Token has expired and should be renewed
  • bad-callback: The callback you supplied does not match that supplied to VivoKey during set-up
  • no-app: The member does not have the VivoKey app installed and thus cannot authenticate with VivoKey
  • declined: The member declined the authorization
  • timeout: The member did not tap to authorize within the given timeout period