PDS Connection API Overview

Please ensure you have your own Dedicated Connection to the Mydex Sandbox before following these steps. To request a Dedicated Connection, please register and login to the Connection Manager and follow the steps to create a connection .

By making a connection to a Personal Data Store of a Mydex member, your service 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 your service.

The Mydex PDS Connection API enables you to establish a secure and unique connection from your service 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 you directly e.g. via an app, an email, SMS invitation or a link within an online account the individual holds with the Subscribing organisation.

Your connections can be from your own back office systems, where there is no user interface, or from your own applications or online accounts that the individual you are connecting to uses.

Connection Scenarios ๐Ÿ”—๏ธŽ click to copy

A Subscriber 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. There are three scenarios for establishing a connection 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 Subscribing organisation wants to send or collect information with them. In this scenario the Subscribing organisation or app invokes the creation of these remotely, and establishes trust between this new personal data store and the Subscribing organisation's services or apps directly.

  2. An individual already has a MydexID and Personal Data Store and wishes to connect it to the Subscribing organisations service or app. This involves what we call "trust binding" or "first time connection", and enables the Subscribing 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 Subscribing organisation holds about the individual which is considered appropriate for granting access to services or data.

  3. The permissions and data-sharing agreement needs to be updated where an individual already has a MydexID and Personal Data Store and is already connected to the Subscribing organisation's service or app. The next time an individual signs in to the service or app using their MydexID, they are asked to review the updated permissions and data-sharing agreement. The last 4 steps in either sequence diagram for scenario 1 or 2 are relevant here starting from "Send permissions and data-sharing approval within themed Mydex page (URL link)".


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

Please note: regardless of which scenario is followed, the payload POSTed to the Subscriber's Dedicated Connection callback URL only occurs after the First Time Connection journey completes (that is, after the member approves the Data Sharing Agreement). No POST is made to the callback after registration of the PDS in Scenario 1.

Important note - This is a trusted API connection ๐Ÿ”—๏ธŽ click to copy

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 Subscribing 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 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 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 Subscribing 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 key is served up by Mydex via a themed Mydex URL to ensure that this information is not retained by the Subscriber organisation or app or Mydex.

Scenario 1: Process flow for MydexID and PDS Creation, followed by First Time Connection to an external service via the Mydex API ๐Ÿ”—๏ธŽ click to copy

Note: this flow involves making a custom registration form with which you will collect the member's desired MydexID and password for sending to our API.

It is recommended that subscribers consider making their application operate as an OpenIDConnect (OIDC) Relying Party (RP) so as to avoid having to collect registration details in their own form. By using OpenIDConnect, you can securely delegate off the registration process to Mydex's own Identity Platform, after which the member is returned to your application to complete the First Time Connection process (thereby ending up something akin to Scenario 2 below).

To explore how to delegate registration off to Mydex by becoming an OIDC RP, please visit the documentation on registration services.

First time connection

1. Collect First Time registration data using a form ๐Ÿ”—๏ธŽ click to copy

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 ๐Ÿ”—๏ธŽ click to copy

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 numerical Connection NID that was provided to you from Mydex when approving your dedicated connection request.

Please note: Make sure to use json decode to properly parse the short access token.

3. Generate hashed authentication token ๐Ÿ”—๏ธŽ click to copy

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 Dedicated Connection token that was provided to you by Mydex when approving your dedicated connection request.

PHP example:

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

4. Make an API Request to begin the registration of the MydexID ๐Ÿ”—๏ธŽ click to copy

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 should 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 https://connection-manager.mydex.org/api-key)
  "connection_nid": "12345",              # The Dedicated Connection NID
  "connection_token_hash": "ABCD1234",    # The SHA512 hash of the Dedicated Connection token
  "return_to": "https://your_connecting_organisation.org", 
}

The following are also used in the request, but are sent as headers:


CURL example ๐Ÿ”—๏ธŽ click to copy

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 https://connection-manager.mydex.org/api-key)
         "connection_nid": "12345",              # The Dedicated Connection NID
         "connection_token_hash": "ABCD1234",    # The SHA512 hash of the Dedicated Connection token
         "return_to": "https://your_connecting_organisation.org", 
        }'
    'https://sbx-api.mydex.org/api/pds'


PHP example ๐Ÿ”—๏ธŽ click to copy

// prepare the array to be posted
$request_data = array(
    'mydexid' => $mydexid,
    'email' => $email,
    'password' => $password,
    'api_key' => $api_key,
    'connection_nid' => $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 ๐Ÿ”—๏ธŽ click to copy

Upon making a successful API call, you will need to decode the JSON response. 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 Key ๐Ÿ”—๏ธŽ click to copy

The member makes up their own private key using a string of characters, a minimum of 8 characters in length. It cannot be the same as the password provided in the previous step. 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 15 minute session length on this.

PEK example

Upon setting their Private Key, the MydexID and PDS is created, and the member will be redirected back to the Subscriber organisation. A query parameter will be appended to the return_to URL as success=1 (a successful result) or success=0 if something went wrong.

7. Retrieve short access token ๐Ÿ”—๏ธŽ click to copy

Repeat Step 2. (above) in order to retrieve a new short access token, for use in the next (and final) step.

8. Complete the First Time Connection journey ๐Ÿ”—๏ธŽ click to copy

You can now invoke a POST request to the /api/connection endpoint with the member's MydexID. This will return a URL that you can json_decode and redirect the member to. The Data Sharing Agreement will be displayed, with the list of datasets that your Dedicated Connection requests access to from the member's PDS. The member will need to enter their Private Key to approve the Data Sharing Agreement.

The member's approval of the Data Sharing Agreement will perform a connection between your Dedicated Connection and the member's PDS. It is at this point that the API will perform a POST request to your application's callback, with a payload containing the member connection key (see here for information on the payload structure). You should store and use these details for future read/write requests to approved datasets in the member's PDS.

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);
๐Ÿ”—๏ธŽ click to copy ftc permissions example

You have now completed the First Time Connection process.

Scenario 2: Connect to an existing MydexID and PDS ๐Ÿ”—๏ธŽ click to copy

PDS Provisioning

Approved Subscriber organisations can allow members with an existing PDS to connect to their Subscribing 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 Subscribing organisation/service, you will need to belong to an Subscribing organisation whose connection has been verified and given the relevant permissions.

Steps to create a connection for a member with an existing PDS: ๐Ÿ”—๏ธŽ click to copy

  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 back to the API when authorising the connection to your Subscribing 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 ๐Ÿ”—๏ธŽ click to copy

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 ๐Ÿ”—๏ธŽ click to copy

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. Use your Subscribing organisationโ€™s Dedicated Connection NID to receive the Short Access Token.

API Address: https://sbx-api.mydex.org
Endpoint: GET /access-token/$connection_nid HTTP/1.1

Parameter Description
$connection_nid [String - required] Your Subscribing organisationโ€™s numerical Dedicated Connection NID provided to you by Mydex when approving your Dedicated Connection.
Example response [JSON encoded String]: ๐Ÿ”—๏ธŽ click to copy

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

PHP Example: ๐Ÿ”—๏ธŽ click to copy
$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: ๐Ÿ”—๏ธŽ click to copy
curl -X GET -H "Content-Type: application/json" 'API-PDS-URL/access-token/CONNECTION_NID

3. Request First Time Connection URL. ๐Ÿ”—๏ธŽ click to copy

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. This URL is the Data Sharing Agreement, which will contain an input field for the Private Key which the member will have to fill in. Once the member submits the form, your Dedicated Connection has made a connection with the member's PDS, the API will POST a payload to the Subscriber organisation service's callback URL, and the member will be redirected back to the Subscriber organisation service.

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_nid,
  "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 Your Dedicated Connection's NID provided to you by Mydex, e.g. 4567 String Y
connection_token_hash The SHA512 hash of the connection_token String Y
return_to The URL to return to the Subscriber organisation String Y

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

PHP Example: ๐Ÿ”—๏ธŽ click to copy
// 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',
);

// 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: ๐Ÿ”—๏ธŽ click to copy
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"
      }'
Example response [JSON encoded string]:
"https:\/\/sbx-api.mydex.org\/app\/connection\/passphrase?token=lwVEMwvmg3HMfKcAURIfQcQ35m%2B3IW5IPFiy5uNOQBI%3D"

After you redirect the member to that URL, this is what they will see:

๐Ÿ”—๏ธŽ click to copy First time connection

After the member enters their Private Key and submits the form, a payload containing the member UID and member connection key is POSTed to your application's callback URL.


Scenario 3: The permissions and data-sharing agreement needs to be updated where an individual already has a MydexID and Personal Data Store and is already connected to the Subscribing organisations service or app. ๐Ÿ”—๏ธŽ click to copy

use-case 3 web-sequence diagram

If you have requested a change to the datasets, fields and/or use case on your dedicated connection after an individual (member) has already connected their personal data store to your service, they will need to approve the connection again before it can be activated. You can use the Connection update API endpoint to call the relevant approval pages from Mydex as part of your own communications and interaction with the individual you are connected to.

This is exactly the same process as with FTC except the endpoint is now /api/connection/update. Your application will need to trigger the Update Connection journey any time a connection record has changed. This includes agreeing to the Data Sharing Agreement to approve access to the PDS. It is advised to keep a record of connection version in your application so any time a change is made to the connection you can use this value to drive which users need to update the Data Sharing Agreement.

Optional Version parameter

If you have made a request for datasets/fields to be added, removed or updated on your dedicated connection via a connection request the connection version will be incremented. Eg. if you requested a new dataset to be added to your connection, we track what changes were made in the new version so the connection goes from version 1 to version 2.

If, within your app, you track the member's connection version (as recommended above) you can pass this value (eg version 1) as part of the POST parameter payload as version. This means we display only the changes to the connection that need to be updated and approved by the member as part of the updated data sharing agreement. If you do not pass this paramter you will see all the permissions the connection is requesting - including those already approved.

The process steps for this are exactly the same as First Time Connection:

Steps to Update a connection for a member who has already connected: ๐Ÿ”—๏ธŽ click to copy

  1. Get a Short Access Token for authentication.
  2. Authenticate member.
  3. Using the Mydex API, a short access token should be requested and then supplied back to the API when authorising the connection to your Subscribing organisation.
  4. The returned response will contain a URL for the Mydex Private Key and updated Data Sharing Agreement. The member can then enter their Private Key to approve the connection which will update their PDS.


Learn how to consume the callback payload to authenticate requests to the member's PDS