Personal Data eXchange 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 using the Personal Data eXchange API to make a connection to a Personal Data Store of a Mydex member your application and service will be able to send and collect personal data relating to that individual seamlessly over a secure connection to remove the need for form filling and manual data entry. eradicating administration effort and the attending Friction, Effort, Risk and Cost it creates. We call that FERC. The PDX API can dramatically reduce FERC.

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

Authenticating to the PDX API 🔗︎ click to copy

OAuth2.0 credentials 🔗︎ click to copy

To access routes on the PDX API (either https://sbx-api.mydex.org for Sandbox or https://api.mydex.org if your connection supports the Live environment), you should authenticate against the PDX API using an OAuth.0 access token, which you obtain from Mydex's OAuth2.0 server using an OAuth2.0 client (using the client_credentials grant).

You can use your OAuth2.0 client credentials to obtain a short-lived access token, which grants you access to routes on the PDX API.

Mydex CIC will supply you with the OAuth2.0 client credentials and scopes when setting up your Dedicated Connection.

OAuth2.0 scopes 🔗︎ click to copy

Your OAuth2.0 client will be carefully scoped to provide access to the routes required.

For all requests to the Mydex PDX API, you must include the scope mydex:pdx when requesting a token. If you are making a request to an individual dataset on the PDX API, thisis the only scope you need when requesting a token.

If you are making use of Mydex's Template System or Feature Blocks, your OAuth2.0 client will also have additional scopes for those purposes. Such scopes reflect the Method and the Endpoint of the request. For example:

get:/api/pds/mam
get:/api/pds/mam/this-is-me/personal-details
put:/api/pds/mam/this-is-me/personal-details
get:/api/pds/mam/this-is-me/contact-details
put:/api/pds/mam/this-is-me/contact-details
post:/api/pds/mam/add-person
delete:/api/pds/mam/delete-person
(etc...)

This is an abridged list. Mydex will tell you the scopes assigned to your OAuth2.0 client when issuing or updating your OAuth2.0 client.

Remember: even when you are requesting a Template or Feature Block endpoint with an Access Token that is scoped to that Method and Endpoint, the access token must also be scoped to mydex:pdx. If in doubt, just include all scopes, including mydex:pdx, when requesting an OAuth2.0 access token.

If you enter an incorrect scope when requesting the token, you will not receive a token back.

To see examples in Python, PHP and Postman of requesting an OAuth2.0 access token from the Mydex OAuth2.0 server, please visit our Github repository.

OAuth2.0 token lifespan 🔗︎ click to copy

OAuth2.0 access tokens have a lifetime of one hour, after which you must request a new access token.

OAuth2.0 servers 🔗︎ click to copy

The Sandbox OAuth2.0 server domain is https://sbx-op.mydexid.org
The Live OAuth2.0 server domain is https://op.mydexid.org

Both servers use /oauth2/token as the token endpoint with which to request an OAuth2.0 token using the client_credentials grant.

If you request a route on the PDX API that is not covered by the scope your token is allowed to use, or if your token has expired, you will see this response from the PDX API:

{
  "error": {
    "message": "Access denied",
    "reason": "Unable to authorize the request. Please make sure you send an OAuth2.0 bearer token or an API key."
  }
}

Dedicated Connection NID and Token 🔗︎ click to copy

In addition to OAuth2.0 credentials, certain actions on the PDX API (such as registering MydexIDs/Personal Data Stores or performing First Time Connections) require the use of your Connection NID and Connection Token, which Mydex also provides to you when setting up the Dedicated Connection.

These requests also require the use of 'short access tokens' which are distinct from OAuth2.0 access tokens.

In some cases, the Dedicated Connection Token and Short Access Tokens need to be concatenated together and sent as a SHA512 hash checksum of the result.

All these authentication details are covered in the examples of the Connection Scenarios below, as well as in helpful API examples (written in Python, PHP and Postman) in this Git repository.

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:

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.

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.

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

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:

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: 🔗︎ click to copy

<?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 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 body payload should look something like this:

{
  "mydexid": "mymydexid",                 # The member's submitted MydexID
  "email": "email@example.com",           # The member's submitted email address
  "password": "XXXXXXXXXXXXXXXXXXXX",     # The member's submitted pasword
  "connection_nid": "45678",              # 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 HTTP headers, not in the POST body payload:

Short-Access-Token (obtained in step 2)
Authentication (SHA512 hash of the combination of the Short-Access-Token and the Dedicated Connection Token, obtained in step 3)
Authorization header. All requests to the PDX API must send a valid OAuth2.0 access token (scoped to mydex:pdx) as the Authorization header, e.g: Authorization: Bearer [token]. Contact us if you have not received OAuth2.0 credentials.
Content-Type application/json

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 page, after which the member will not be able to successfully submit the form.

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. Commence the First Time Connection journey 🔗︎ click to copy

Although the member has now created a MydexID and PDS, they still need to accept the Data Sharing Agreement terms to consent to their data being shared with your Dedicated Connection service. We call this the 'First Time Connection' journey.

To commence the First Time Connection journey, follow the steps in Scenario 2, which are documented below.

Scenario 2: Connect to an existing MydexID and PDS

First Time Connection to an existing MydexID

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

Create a simple login form on your platform. This form will post to the Mydex API with the Member’s credentials.
Get a Short Access Token for authentication.
Generate a SHA512 hash of the Short Access Token combined with the Dedicated Connection token.
Get an OAuth2.0 access token from Mydex's OAuth2.0 server
Make a request to the PDX API's /api/connection endpoint with the expected payload (described below)
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.

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.

cURL Example: 🔗︎ click to copy

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

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.

3. Generate hashed authentication token 🔗︎ click to copy

PHP Example: 🔗︎ click to copy

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

4. 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 (header): application/json
Authentication (header): hash(SHA512, SHORT-ACCESS-TOKEN + CONNECTION-TOKEN)
Authorization (header): OAuth2.0 access token, scoped to mydex:pdx
Short-Access-Token (header): SHORT-ACCESS-TOKEN
JSON (body payload):

'{
  "mydexid" : $mydexid,
  "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
connection_nid	Your Dedicated Connection's NID provided to you by Mydex, e.g. 45678	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

Example response [JSON encoded string]:

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

Remember: Use JSON Decode to parse the URL from the response.

PHP example 🔗︎ click to copy

Click here to view the PHP example

Python example 🔗︎ click to copy

Click here to view the Python example

Postman example 🔗︎ click to copy

Click here to view the Postman example

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

🔗︎ click to copy

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 member is already connected but the permissions and Data Sharing Agreement need to be updated/reapproved

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