Connection API Overview

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

Connections can be invoked remotely via the Connection API or from within a member's Personal Data Store by selecting the connection from the directory of apps and services. This allows organisations to design their own customer journeys to suit their own business requirements and brand guidelines.

The Connection Process Options

Invoked from within a member's Personal Data Store

  1. A Mydex member initiates a connection from within the Mydex directory. This invokes a connection wizard which establishes trust between their Personal data store and the external connection.
    1. We call this trust binding and it involves the individual providing specific information that the connecting organisation requires to match their PDS to their records within the organisation.
  2. After trust is bound, the member then grants access to the connection based on the predefined set of approved use cases for the data that is to be exchanged, and a specific set of permissions relating to those datasets. These can be combinations of the following:
    1. Simple read access to data upon demand.
    2. The ability to deliver to and store data in the PDS either automatically, or queue it up for the member to approve the updating of the PDS.
    3. The ability to automatically receive updates or changes made to data held in the PDS.
  3. Once approved, a callback is fired, sending authentication information from Mydex platform to the connection's server which completes the connection.
  4. The Connection API can now be used to read/write member data according to the data sharing agreement. See more details on the Connection API.

Remotely invoked connection

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 Connection API. We support two specific contexts as follows:

The specific customer journey is under the control of the organisation so that it can be modified to meet different needs. For example, returning the individual to the App or directly to their PDS and records delivered from their new connection or back to an organisations website.

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 is based on a unique combination identifiers. The individual or the organisation can revoke the connection at any time.

A Note on Using iFrames

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.

Process Flow for External PDS Create, and First Time Connection Via the Mydex API

1. Collect Member Data

The PDS Create API requires the following items of member data:

This is in addition to those parameters that are required for the API request itself:

During development, API requests should be made to the Mydex Developer Test Connection (Connection Node ID 1545). We can issue a connection token for use on Sandbox on request for testing purposes. This can be requested by emailing Developer Support. For creating a connection on the live platform, organisations must complete a series of steps that ensure for our members and other participants that they comply with the terms of connections. The process of verification, inspection and certification is manual today but is being automated as much as possible via our connection management service.

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

2. Obtain the Short Access Token

The 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. Use Json Decode to get the short access token.

3. Make an API Request

The Mydex Sandbox API endpoint is:

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

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   
        }' 
    'https://sbx-idp.mydexid.org/api/pds'

4. Handle 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.

5. Get the URL from JSON

Extract the URL from the JSON object. This is the URL that you need to embed into your iframe in order to load the Mydex Private Key app. It is possible to manipulate this URL with the following parameters:

Parameter Name Parameter Value Example Description
First Time Connection ftc 1 &ftc=1 Adding this parameter triggers the automatic creation of the connection, in addition to the PDS creation.
Return URL return_to any &return_to=http://mydex.org Adding this parameter will add a return url into the verification email so that members can be returned back into the 3rd party process.

Example URLs for use in the iframe

PDS Create only:

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

PDS Create with First Time Connection:

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

PDS Create with First Time Connection and Return URL:

https://sbx-idp.mydexid.org/app/passphrase?token=TOKEN&ftc=1&return_to=RETURNURL

6. Embed URL in an iframe

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.

7. Member Enters Private Encryption Key

At this point the member will be able to set their private key within the iframe, and hit submit once they are happy.

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

8. Check Email

Upon setting their Private Encryption Key, an email will be sent to a member 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.


The Authentication Process