PDS Create and First Time Connection

Approved connecting organisations can trigger the creation of a new PDS via an API call. This is normally done in the context of a first time connection when driving a new member to the Mydex platform, with information provided by that organisation. This function can currently only be used on the Sandbox server.

In order to be able to create a new PDS, you will need to belong to an organization whose connection has been verified and given permission to create PDS accounts. You will have been issued a token unique to this connection that must be included as a parameter in the API call.

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.