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.

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:

• MydexID: This must be completely alphanumeric, not contain only numbers, and be a minimum of 3 and maximum of 60 characters long.
• Email: A valid email address should be used as the PDS will set this as the recipient of all emails related to that account.
• Password: The password that will be used to access the PDS, it must have a minimum of 8 characters.

Example of a custom built form that you may create:

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:

• API Key: The API key can be found within your developer account.
• The Connection NID
• Connection Token Hash: This is the SHA512 hash of the Dedicated Connection token that was provided to you by Mydex when approving your dedicated connection request.

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:

• Short Access Token (obtained in step 2)
• Hashed authentication token (obtained in step 3)

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.

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);

Scenario 2: Connect to an existing MydexID and PDS 🔗︎ click to copy

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.

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

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",
}';

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:

---

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

---

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