PDS Connection API Overview

Ensure you have your own connection to the Mydex platform before following these steps. Until you have one please use the developer test connection guide.

By making a connection to a Mydex member, a connecting organisation will be able to receive and share data relating to that individual. This helps the individual to manage their personal data more effectively in a secure and convenient way and streamlines their interactions with the organisation. In addition, this creates new services and customer journeys.

The Mydex PDS Connection API enables a connecting organisation to establish a secure and unique connection with an individual's Personal Data Store (PDS) where one already exists. It can also trigger the creation of a MydexID and Personal Data Store as part of a process controlled by the organisation e.g. via an app, an email invitation or a link on a website.

A connection can take one of two forms; either connections to one or more of an organisation's internal systems, or a connection to an application the individual will use that is running outside of the Mydex platform e.g. on a mobile, tablet or desktop device or an application running within a website itself.

Use cases

A connecting organisation may wish to invite its customers to connect their PDS to their records, or to connect an App to their PDS. We call this remote invocation of a connection and it is orchestrated via the PDS Connection API and also calls the IDP-API for first time connection. We support two specific contexts as follows:

  1. An individual is a customer or user of an existing service but does not yet have a MydexID and personal data store and the organisation wants to send or collect information with them. In this scenario the organisation or app invokes the creation of these remotely, and establishes trust between this new personal data store and the organisation's services or apps directly.
  2. An individual already has a MydexID and Personal Data Store and wishes to connect it to the organisations service or app. This involves what we call "trust binding" or "first time connection", and enables the organisation to validate that the individual is their customer and entitled to establish the connection. This can use a range of methods but relies on information the organisation holds about the individual which is considered appropriate for granting access to services or data

The specific customer journey is under the control of the organisation so that it can be modified to meet different needs.

Important note - This is a trusted API connection

Once the connection between a personal data store and an app or service is established and trust is bound there is no requirement for ongoing authentication via login using a MydexID and password. The connection is persistent and encrypted. It is based on a unique combination of identifiers. The individual or the organisation can revoke the connection at any time.

Mydex as a Trust Framework and ISO27001 certified service offer individuals the ability to store their personal data and connection records in individually encrypted Personal Data Stores that are under their total control. Mydex has no access to their data and to ensure that the individual remains totally in control we require them to use a private encryption key which only they know and set. This is in addition to their selection of their MydexID and password. If they lose this private encryption key or forget it Mydex is not able to recover it as we do not hold it.

To ensure the highest level of security for our members when a connecting organisations wishes to invoke the creation of a new Mydex PDS for its customers or users, Mydex provide a set of API functions to make this possible. However the step that involves selection and confirmation of the private encryption key is served up by Mydex via an iframe to ensure that this information is not retained by the connecting organisation or app or Mydex. The iFrame itself in terms of size, look and feel can be controlled by the connecting organisation or app.

Use case 1: Process flow for MydexID and PDS Creation, followed by First Time Connection to an external service via the Mydex API

1. Collect First Time registration data using a form

The MydexID and PDS Create APIs require the following items of member data and you should collect these details on a registration form you create:

Example of a custom built form that you may create:

2. Obtain a Short Access Token

A Short Access Token can be accessed using a curl request:

  curl -X GET -H "Content-Type: application/json" 'https://sbx-idp.mydexid.org/access-token/:con_nid'

Where :con_nid is the Connection Node ID. This is the second number in the Connection ID, eg 123-4567. Then use json decode to get the short access token.

3. Generate hashed authentication token

A hashed authentication token is required for the API request. It is generated by taking the SHA512 hash of the short access token concatenated with the connection token.

PHP example:

<?php $hashed_auth_token = hash('SHA512', $short_access_token . $connection_token); ?>

4. Make an API Request

The Mydex Sandbox API endpoint is:

https://sbx-idp.mydexid.org/api/pds

In API the request you will send the user's details obtained in step one. In addition to these, the following details are required in the POST data:

The POST data will then look something like this:

{
  "mydexid": "mymydexid",                 # The member's MydexID
  "email": "email@example.com",           # The member's email
  "password": "XXX",
  "accept_legal": "TRUE",
  "api_key": "XYZ123",                    # The developers's API key (found under 'Account' on dev.mydex.org)
  "connection_nid": "12345",              # The connection node ID
  "connection_token_hash": "ABCD1234",    # The SHA512 hash of the connection_token
  "iframe_expire": "120",                 # Optional - iframe expiration time in seconds
}

The following are also used in the request:


CURL example

An example CURL API request is:

curl
    -X POST
    -H "Content-Type: application/json"
    -H "Authentication: hashed_auth_token"       # SHA512 hash of "short_access_token"+"connection_token"
    -H "Short-Access-Token: short_access_token"  # The short access token obtained from step 2.
    -d '{"mydexid": "mymydexid",                 # The member's MydexID
         "email": "email@example.com",           # The member's email
         "password": "XXX",
         "accept_legal": "TRUE",
         "api_key": "XYZ123",                    # The developers's API key (found under 'Account' on dev.mydex.org)
         "connection_nid": "12345",              # The connection node ID
         "connection_token_hash": "ABCD1234",    # The SHA512 hash of the connection_token
         "iframe_expire": "120",                 # Optional - iframe expiration time in seconds
         "iframe_style": "120",                 # Optional - iframe expiration time in seconds // TODO: ADD
        }'
    'https://sbx-idp.mydexid.org/api/pds'


PHP example

// prepare the array to be posted
$request_data = array(
    'mydexid' => $postdata->mydexid,
    'email' => $postdata->email,
    'password' => $postdata->password,
    'accept_legal' => $postdata->legal,
    'api_key' => $postdata->api_key,
    'connection_nid' => $postdata->connection_nid,
    'connection_token_hash' => hash('SHA512', $connection_token),
    'iframe_expire' => '300',
    'iframe_style' => array(
        'resource' => 'body{background-color: #D3D3D3;} label{color: #00FF00;} .form-control{color: blue;}',
    ),
    'iframe_content' => array(
        'label-access-key' => 'Private Key:',
    ),
);

// compute authentication key based on the previous short access token
$authentication = hash('SHA512', $short_access_token.$connection_token);

$idp_request_url = MYDEX_IDP_PATH . '/api/pds';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $idp_request_url);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authentication: ' . $authentication,
    'Short-Access-Token: ' . $short_access_token,
));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode((object)$request_data));

$pdsCreateRequest = curl_exec($ch);
$curl_error = curl_error($ch);
curl_close($ch);

You can download a generic Python 2.7 script demonstrating the use of the 'Create PDS' functionality by clicking below. The parameters in the script will need to be updated with your own information, such as your developer API key, the email address of the account you wish to create, and so on. This script can be run on modern OS X and most modern Linux distributions by opening the file location in the terminal and running python pds_create_demo.py. The script will print the iframe URL returned by the API.

Demo Python Script

5. Handling the JSON response

Upon making a successful API call, you will need to decode the JSON return. In PHP you can do this using the json_decode() function. This response will give you the iframe URL which you will need to embed this into an iframe in order to load the Mydex Private Key app. The URL will be of the form

https://sbx-idp.mydexid.org/app/passphrase?token=TOKEN

It is possible to manipulate this URL by adding the following parameters:

Parameter Name Parameter Value Example Description
Return URL return_to any &return_to=http://mydex.org This is essential. Adding this parameter will add a return url into the verification email so that members can be returned back into the 3rd party process. If this is not present in the URL, the user will be taken to the Mydex PDS site instead of back to your application.

6. Embed URL in an iframe to process the Private Encryption Key for approving the connection

Embed the URL generated above into a HTML iframe. It is up to you what dimensions you give the iframe; width is not an issue as the content is responsive, although it is recommended not to be smaller than 220px in width. The absolute minimum height is 222px, but this is without error messages/alerts which mean iframe overflow will need to be handled, or the iframe made scaleable in a vertical direction.

By modifying the iframe_style array in step 4 above, the iframe can be styled to fit your organisation's desired styling and brand. Below is an example of a modified iframe_style array, followed by the iframe we created for our Z9 simulated connection.

Example array:

'iframe_style' => array(
    'resource' => 'body{
        background: url(ABSOLUTE_URL_FOR_BACKGROUND_IMAGE) no-repeat #FAF7EB 95% 5%;
        padding-top: 40px;
    }
    label{
        color: #104163;
    }
    .form-control{
        color: blue;
    }',
),

Styled iframe:

7. Member creates their Private Encryption Key

The member makes up their own private encryption key using a string of characters, a minimum of 8 characters long. This is used to control the encryption of their personal datastore and the means of approving connections to their personal datastore. Only the individual knows this and it cannot be retrieved or reset by Mydex in order to maintain our zero-knowledge platform architecture.

Note: There is currently a 60 second session length on this iframe.

8. Check Email

Upon setting their Private Encryption Key, an email will be sent to the individual in order to validate their email address obtained from step 1 above, and then return them back into the external user journey from where they came. The link that returns them back into their user journey is set in the return_to parameter on the iframe URL (step 5).

The page that you create should allow the individual to see the connection's permissions and approve them, see step 9 below.

9. Call permissions list from your dedicated connection for approval

As part of the connection process you are securing informed consent for the permissions to send and receive data between you and the individual's personal data store. You need to request the list of permissions that you want approved by the individual. Here is a PHP example that is used in our simulated connections code.


  $api_idp_token_url = 'https://sbx-idp.mydexid.org/access-token/' . $connection_nid;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $api_idp_token_url);
  curl_setopt($ch, CURLOPT_HEADER, 0);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  $token_request = curl_exec($ch);
  $short_access_token = json_decode($token_request);
  curl_close($ch);

  if (isset($short_access_token->error)) {
    $return_data = array(
      'error' =>'Short access token error.',
    );
  }

  $authentication = hash('SHA512', $short_access_token . $connection_token);

  $idp_request_url = 'https://sbx-idp.mydexid.org/connection/' . $connection_nid . '/permissions';
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $idp_request_url);
  curl_setopt($ch, CURLOPT_HEADER, 0);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authentication: ' . $authentication,
    'Short-Access-Token: ' . $short_access_token,
  ));

  $connection_permissions_request = curl_exec($ch);
  $connection_permissions = json_decode($connection_permissions_request, true);
  curl_close($ch);

The data returns the dataset name, the label for the field and denotes whether you have read or write access, or both. Here is a short example of the returned data.

{"field_ds_personal_details":{"label":"Personal Details","instance":true,"fields":{"field_personal_email_address":{"value":"field_personal_email_address","r":true,"w":true,"label":"Email Address"},"field_personal_faname":{"value":"field_personal_faname","r":true,"w":true,"label":"Family Name"},"field_personal_fname":{"value":"field_personal_fname","r":true,"w":true,"label":"First Name"}}}}

How you present the returned data using your environment is entirely up to you. In our simulated connections we are using bootstrap and an accordian to allow each dataset to be expanded for review. Example below for Z9 connection simulation.

Permissions



Permissions

You will also need the first time connection private encryption key iFrame for approving the connection. As with all iframes you can control the look and feel of them.

PHP Example

// Prepare the array to be posted.
$request_data = array(
    'mydexid' => $mydexid,
    'api_key' => $api_key,
    'connection_nid' => $connection_nid,
    'connection_token_hash' => hash('SHA512', $connection_token),
    'iframe_expire' => '300',
    'iframe_style' => array(
        'resource' => 'body{background-color: #D3D3D3;} label{color: #00FF00;} .form-control{color: blue;}',
    ),
    'iframe_content' => array(
        'ftc-access-key' => 'Private Key:',
    ),
);

// You will need to obtain a short access token as previously (step 2 above).
$authentication = hash('SHA512', $short_access_token . $connection_token);

$idp_request_url = 'https://sbx-idp.mydexid.org/api/connection';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $idp_request_url);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authentication: ' . $authentication,
    'Short-Access-Token: ' . $short_access_token,
));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode((object) $request_data));

$ftc_request = curl_exec($ch);
$curl_error = curl_error($ch);
curl_close($ch);

10. Confirmation email

The completion of the connection process results in an email being sent to the individual confirming the connection is now established.


Use case 2: Connect to an existing MydexID and PDS

Approved connecting organisations can allow members with an existing PDS to connect to their organisation/service via an API call. The context for this type of connection is ‘First time connection for a member with an existing PDS’.

In order to be able to connect members to your organisation/service, you will need to belong to an organisation whose connection has been verified and given the relevant permissions.

Steps to create a connection for a member with an existing PDS:

  1. Create a simple login form on your platform. This form will post to the Mydex API with the Member’s credentials and your Mydex Developer API Key as authentication in the header.
  2. Get a Short Access Token for authentication.
  3. Authenticate member.
  4. Check to see if the member has already set up the connection.
  5. If the connection doesn’t already exist, then using the Mydex API, a short access token should be requested, and then supplied to back to the API when authorising the connection to your organisation.
  6. The returned response will contain an iframe URL for the Mydex Private Key iframe. The member can then enter their Private Key to authenticate and complete the connection to their PDS. This iframe will utilise the optional ‘iframe_style’ string to override the default styles

See the following for a more detailed breakdown of each one...

1. Create a simple login form on your platform

Create a simple HTML form with two input fields to submit the MydexID and Password of the member for authenticating the connection (see example image below).

When the user submits the form, in the POST handler for the form, go through the next steps.

2. Get a Short Access Token for Authentication

To set up a connection to a PDS a Short Access Token is required to authenticate the API call and return the iframe, which in-turn allows the member to authenticate the connection. Simply POST your organisation’s Connection ID to receive the Short Access Token.

API Address: https://sbx-idp.mydexid.org
Endpoint: POST /access-token/$connection_nid HTTP/1.1

Parameter Description
$connection_nid [String - required] Your organisation’s connection ID provided to you by Mydex when you setup your connection.

Example response [JSON encoded String]:

"lpPF3DqUa16mls\/gbM4QbM5OZi8vL0djC+mG+ZdZb3c="
Please note: use JSON Decode to parse the Short Access Token from the response.

PHP Example

$api_idp_token_url = $api_idp_url . '/access-token/' . $connection_nid;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_idp_token_url);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$tokenRequest = curl_exec($ch);
$short_access_token = json_decode($tokenRequest);
$curl_error = curl_error($ch);
curl_close($ch);

cURL Example

curl -X GET -H "Content-Type: application/json" 'API-IDP-URL/access-token/CONNECTION_NID

3. Authenticate Member

The first step is to put the member credentials (from step 1) into an authentication array:

$auth_data = array(
'mydexid' => $mydexid,
'password' => $password,
'connection_nid' => $connection_nid,
);

To authenticate the member, a hash value (SHA512) needs to be created using the short access token and connection token e.g.

$authentication = hash('SHA512', $short_access_token.$connection_token);

This hash value should be passed as the authentication in the post to the endpoint, along with the short access token:

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authentication: ' . $authentication,
'Short-Access-Token: ' . $short_access_token,
));

Set the json encoded $auth_data in the request using CURLOPT_POSTFIELDS:

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode((object)$auth_data));

Then execute the curl request and check and handle the result. If there is no error, then proceed to the next step.

API Address: https://sbx-api.mydex.org
Endpoint: POST /app/authentication
Content-Type: application/json

Parameter Description
$mydexid [String - required] Value of the MydexID field
$password [String - required] Value of the Password field
$custom_css [String - optional] A string of custom CSS to style elements in the iframe returned - this CSS will be appended as a <style> tag in the head of the returned iframe. An example string: “body{background-color: #D3D3D3;} label{color: #00FF00;} .form-control{color: blue;}”. Please note: all strings will be parsed/linted, removing any html/script tags or similar.

Example response [JSON object]:

{"id":"ID","mydexid":"MYDEXID","email":"EMAIL","created":"TIMESTAMP"} 

4. Check to see if the member has already set up the connection.

This functionality is currently on our development roadmap, along with a range of other ‘developer helper’ functions. Our recommendation in the meantime is that when you initially connect to a member on the Mydex platform, you store the callback information (conn key, member id, etc.) in a local database to use as an internal lookup for determining this.

If the member is not already connected, proceed with steps 5,6, and 7.

5. Get a Short Access Token for Authentication

Since short access tokens can only be used once, request a new one by following the same procedure as in step 2.

The new short access token will be used to request the First Time Connection Iframe URL.

6. Request First Time Connection Iframe (if member not already connected)

The following API call uses the previously acquired short access token. In the table below one can find examples of the labels/content that can be altered in the iframe. Style can be ‘injected’ as well using the ‘iframe_style’ variable in the body of the request.

The API will return an iframe URL which will be embedded on your website after the login form. The iframe will contain an input field for the Private Key which the member will have to fill in. Once the member submits the form inside the iframe they will be prompted with a message whether the connection has been successful or not.

You must also display the permissions for approval, following the same process as use case 1 (step 9).

API Address: https://sbx-idp.mydexid.org
Endpoint: POST /api/connection HTTP/1.1
Content-type: application/json
Authentication: hash(SHA512, SHORT-ACCESS-TOKEN + CONNECTION-TOKEN)
Short-Access-Token: SHORT-ACCESS-TOKEN
JSON:

'{
"mydexid" : $mydexid,
"api_key": $api_key,
"connection_nid": $con_id,
"connection_token_hash": $connection_token_hash,
"$iframe_style": $iframe_style
"iframe_content": $iframe_content,
}';
Parameter Description Type Required
mydexid The member MydexID String Y
api_key Your connection API Key String Y
connection_nid The second number in your Connection ID e.g. 123-4567 String Y
connection_token_hash The SHA512 hash of the connection_token String Y
iframe_style An array containing with one element with the ID “resource”. The value of this element will be the custom CSS you wish to use to style elements in the iframe - this CSS will be appended as a <style> tag in the head of the returned iframe.
An example of a json array is the following:
iframe_style":{
"resource":"body{
background-color: #D3D3D3;
}
label{
color: #00FF00
}
.form-control{
color: blue;
}"
}
Please note: all strings will be parsed/linted, removing any html/script tags or similar.
Array Optional
iframe_content An array of key => values, where the keys are the IDs of the HTML tags in the iframe, and the values are the content of the html tags.The default array of values used in the PDS Create iframe are the following (in json format):

"iframe_content":{
"ftc-access-key":"Private Key:",
"edit-submit":"Submit",
"ftc-success-message":"Thank you. The connection has been added successfully.",
"ftc-error-message":"There was an error connecting with the organization."}
}
When sending the changed values you can omit the ones that do not need changing, and only send the IDs that do need changing.
You can also omit this property entirely as it is optional.
All strings will be parsed and all tags will be removed with the exception of <b>,<i>,<br>, and <p>
Array Optional

Example response [JSON encoded string]:

"https:\/\/sbx-idp.mydexid.org\/app\/connection\/passphrase?token=lwVEMwvmg3HMfKcAURIfQcQ35m%2B3IW5IPFiy5uNOQBI%3D"

Please note: use JSON Decode to parse the iframe URL from the response.

PHP Example

// prepare the array to be posted
$request_data = array(
'mydexid' => $postdata->mydexid,
'api_key' => $postdata->api_key,
'connection_nid' => $postdata->connection_nid,
'connection_token_hash' => hash('SHA512', $connection_token),
'iframe_expire' => '300',
'iframe_style' => array(
  'resource' => 'body{background-color: #D3D3D3;} label{color: #00FF00;} .form-control{color: blue;}',
),
'iframe_content' => array(
  'ftc-access-key' => 'Private Key:',
),
);

// compute authentication key based on the previous short access token
$authentication = hash('SHA512', $short_access_token.$connection_token);

$idp_request_url = MYDEX_IDP_PATH . '/api/connection';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $idp_request_url);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authentication: ' . $authentication,
'Short-Access-Token: ' . $short_access_token,
));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode((object)$request_data));

$ftcRequest = curl_exec($ch);
$curl_error = curl_error($ch);
curl_close($ch);

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authentication: 101c88d71c8c979147d71c776ed7a2c453f2f30ba6be0ea96c572fac40d19546fef0480119b4be8469d35c502b5f62004467cf34fe8615a4400ade03ef8ad4ac" -H "Short-Access-Token: E8YomDv2NjRE967XwjuSQmDfmaIhSUCZKWeE+vm+wAA="  -d '{"mydexid":"mymydexid","api_key":"XYZ123","connection_nid":"12345","connection_token_hash":"ABCD1234","iframe_style":{"resource":"body{background-color: #D3D3D3;} label{color: #00FF00;} .form-control{color: blue;}"},"iframe_content":{"ftc-access-key":"Private Key:"}}' 'API-IDP-URL/api/connection

Private Key - First Time Connection iframe screenshot and markup:

The Mydex Private key - First time connection iframe markup is built using vanilla Bootstrap (getbootstrap.com). Please see screenshot below and markup available for you to create your own custom CSS. Please note the Submit button will remain in a disabled state (handled via jQuery) until the minimum 8 characters and a matching Private Key is entered.

Please see the Mydex Private Key - First Time Connection iframe markup below - complete with class names available for you to create your custom CSS string.

<body>
<div class="container-fluid">
<div class="col-sm-12">
<div class="row">
  <section>
    <form id="mydex-api-identification-connection" accept-charset="UTF-8" method="post" action="">
      <div class="form-group">
        <label id="ftc-access-key" class="control-label" for="edit-access-key"></label>
        <input id="edit-access-key" class="form-control required" type="password" maxlength="60" size="15" value="" name="access_key"></input>
      </div>
      <input type="hidden" value="" name="return_to"></input>
      <input type="hidden" value="g52t6IarhPfqfqtx039gwH5hrKA78s4KTPATVaW3Hd8=" name="token"></input>
      <div id="edit-actions" class="form-group clearfix"></div>
    </form>
  </section>
</div>
</div>
</div>
<script type="text/javascript"></script>
<script src="https://js-agent.newrelic.com/nr-476.min.js"></script>
</body>

By modifying the iframe_style array in step 6 above, the iframe can be styled to fit the connecting organisation’s desired display scheme. Below is an example of a modified Iframe_style array, followed by the iframe it produces:

Example array:

'iframe_style' => array(
'resource' => 'body{
  background: url(ABSOLUTE_URL_FOR_BACKGROUND_IMAGE) no-repeat #FAF7EB 95% 5%;
  padding-top: 40px;
}
label{
  color: #104163;
}
.form-control{
  color: blue;
}'
),

Styled iframe: