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 PDS-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. To ensure that the individual remains totally in control we require them to use a private encryption key which only they know and set to approve any connections or changes them or remove them. 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 a themed Mydex URL to ensure that this information is not retained by the connecting organisation or app or Mydex.

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

First time connection

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:

Iframe example

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-api.mydex.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-api.mydex.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",
  "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
  "return_to": "https://your_connecting_organisation.org", 
}

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",
         "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
         "return_to": "https://your_connecting_organisation.org", 
        }'
    'https://sbx-api.mydex.org/api/pds'


PHP example

// prepare the array to be posted
$request_data = array(
    'mydexid' => $postdata->mydexid,
    'email' => $postdata->email,
    'password' => $postdata->password,
    'api_key' => $postdata->api_key,
    'connection_nid' => $postdata->connection_nid,
    'connection_token_hash' => hash('SHA512', $connection_token),
    "return_to": "https://your_connecting_organisation.org",
    ),
);

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

$pds_request_url = MYDEX_PDS_PATH . '/api/pds';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $pds_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);

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 URL which you will need to redirect the member to in order to load the Mydex Private Key app. The URL will be of the form

https://sbx-api.mydex.org/app/passphrase?token=TOKEN

6. 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.

PEK example

Upon setting their Private Encryption Key the member will be redirected back to the connecting organisation.

7. Retrieve short access token

Repeat Step 2. (above) in order to retrieve a new short access token.

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),
    'return_to' => 'https://your_connecting_organisation.org',
    ),
);

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

$pds_request_url = 'https://sbx-api.mydex.org/api/connection';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $pds_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);

ftc permissions example

You have now completed the First Time Connection process. On success the member will be redirected back to your service. A callback will be made to your API endpoints with the member connection details.


Use case 2: Connect to an existing MydexID and PDS

PDS Provisioning

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. 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.
  5. The returned response will contain a URL for the Mydex Private Key. The member can then enter their Private Key to approve the connection and complete the connection to their PDS.

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 one input field to capture the MydexID of the member.

Mydex login

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 URL, which in-turn allows the member to approve the connection. Simply POST your organisation’s Connection ID to receive the Short Access Token.

API Address: https://sbx-api.mydex.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_pds_token_url = $api_pds_url . '/access-token/' . $connection_nid;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_pds_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-PDS-URL/access-token/CONNECTION_NID

3. 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 URL.

4. Request First Time Connection URL.

The following API call uses the previously acquired short access token. In the table below one can find examples of the content.

The API will return an URL which you will redirect the member to after capturing their MydexID. The URL will contain an input field for the Private Key which the member will have to fill in. Once the member submits the form they will be redirected back to the Conncting organisation service.

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

API Address: https://sbx-api.mydex.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,
"return_to":"https://your_connecting_organisation.org",
}';
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
return_to The URL to return to the connecting organisation String Y

Example response [JSON encoded string]:

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

5. Completing the connection.

Please note: use JSON Decode to parse the 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),
'return_to'=> 'https://your_connecting_organisation.org',
  ),
};

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

$pds_request_url = MYDEX_PDS_PATH . '/api/connection';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $pds_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"

First time connection

You have now completed the First Time Connection process.