Overview

Overview

Implementing Validic Connect with your Application

At the end of the implementation process, your application will appear in our Validic App Marketplace and your users will be able to authorize their data to be shared with our growing list of health and wellness customers.

Important Concepts Before you Begin your Integration

Once you have your Organization Credentials, we recommend reviewing our Enterprise API Documentation to understand the basic concepts of Validic Organizations, User Provisioning and the Validic App Marketplace. You may also want to review the documentation in the Objects section for reference on how to send your users’ health data to Validic.

Step 1: Apply for Validic Connect Credentials

In order to get started with Validic Connect, you’ll need to Apply for API Credentials. Once registered, you will receive the following back from us:

1. Partner Organization ID
2. Partner Organization Access Token
3. Consumer Testing credentials (including consumer organization ID, consumer organization access token and user access token)

Note: Soon after being registered and receiving these from Validic, you should submit to us a Notification URL (see Receiving Sync Notifications and Receiving Disconnect Notifications below).

Step 2: Setup User Authentication

The Authentication process verifies that a user intending to share their data from your application is in fact the owner of that data. Following standard OAuth implementation, you’ll need to create a separate authentication page (different than your usual log in area) where users can verify their identity and subsequently authorize their data to be shared. Once your user is successfully authenticated in your application, you’ll need to send us a unqiue identifier to associate your user with a user in Validic Connect.

Determine a UID for Your Users

Determining your user’s unique identifier (uid) to send to Validic Connect is the first step in the user authentication and authorization process.  A user’s uid is their unique identifier in your system which you will submit to Validic during authentication. Your user’s uid should be a random string of letters and numbers, unique to each user in your application, and cannot be any kind of objectively identifiable field such as an email address, name, social security number, etc. Most partners choose their user’s standard ID. Note: if you attempt to us an email address as a uid it will result in a 422 Unprocessible Entity from Validic.

If you do not already have an acceptable unique identifier for each of your users, you may generate one for them. This can be done on the fly or in bulk depending on your preferences; however, it must be done before confirming authentication (see next section). If you choose to generate a UID on the fly, you must persist that UID as part of that user’s record in your system and check for a UID before generating a new one. This will ensure that if a user syncs a second time your system will submit the same UID to Validic. Otherwise a duplicate user will be created in Validic.

Create an Authentication Page

You will need to create an authentication page separate from your standard login area at the Authentication URL you provided. When a user intends to share their data with a “consumer” (for example a health portal or EMR system), Validic will send users to your authentication URL to verify their identity.

Sample Authentication Page URL
https://yourdomain.com/your_authentication_url

The request from Validic Connect to your Authorization URL is a 302 redirect that will include two URL parameters:

• sync_url – where your application will send a POST request (see below) to confirm successful authentication
• signature – url encoded signature from Validic to verify your POST request back to Validic

You will need to temporarily retain both parameter values to be used after user authentication..

Authenticating Users Who Want to Share Data

Once your user has successfully authenticated, you’ll need to send a POST request to the sync_url with the following parameters:

• uid – your users uid as a string
• signature – signature generated and given to you by Validic Connect

POST https://{sync_url}
-H 'Content-Type: application/json'
{
  "uid": "{YOUR_USERS_UID}",
  "signature": "{SIGNATURE}"
}

The POST request to the sync_url will respond with the following JSON response, provided the uid sent is unique and not an email address.

{
  "code": 201,
  "message": "Authorized",
  "user": {
    "_id": "VALIDIC_USER_ID",
    "uid": "YOUR_USER_UID",
    "access_token": "VALIDIC_USER_ACCESS_TOKEN"
},
  "application": "THIRD_PARTY_APPLICATION_NAME",
  "redirect_uri": "VALIDIC_REDIRECT_URI"
}

A successful authentication confirmation will receive a 201 response which includes your user’s information in Validic, a redirect_uri, and the third-party application’s name. For those familiar with Validic’s User Provisioning process, this request has provisioned a user in Validic with the uid you send in the POST request. Your application should store the Validic user _id, in addition to the Validic user access_token as attributes of your user that has just authenticated. You may also store the “consumer” application name should you choose to display this as part of “consumer” applications your user has authenticated.

Redirecting the User

Once you’ve saved the _id and access_token from the Sync URL POST response, you should redirect the user to the redirect_uri given in the response. At this point, your interaction with the user who would like to share their data is complete. Validic will display a final authorization confirmation page to the user and upon this final confirmation by the user, the third party application will then be able to receive your user’s data.

Step 3: Submitting your App to the Validic Marketplace

Upon completion of your application and once you decide that it is ready for release, you must then apply for Application Approval with Validic. To do so, please contact partner-support@validic.com with the name of your application. Once approved, your app will be available to our customers as an official part of the Validic Marketplace.

View More >