IDP API iframe Content Injection

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 (SBX) server.

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

To create a Mydex PDS and connect to your service requires a process of two api calls:

  1. Request a Short Access Token for authentication
  2. Request the iframe URL using the Short Access Token

See the following for a more detailed breakdown of each one…

1. Request a Short Access Token for authentication

API Address: https://sbx-idp.mydexid.org
Endpoint: GET /access-token/$connection_id HTTP/1.1
Content-Type: application/json

Parameter Description
$connection_id [required] The second number in your Connection ID e.g. 123-4567

Example response [JSON encoded String]:

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

PHP Example

$api_idp_token_url = $api_idp_url . '/access-token/' . $connection_nid;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_idp_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

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

2. Request the iframe URL using the Short Access Token

For this API call a simple form is required (see example below). This form should be built and themed accordingly on your own platform. Submitting this form using the Mydex API endpoint will return an iframe URL, which will contain the Private Key key creation iframe. This iframe is built using vanilla Bootstrap markup, and allows injection of a CSS string which will be inserted as a <style> tag to the head of the iframe. This allows you to theme/customise the iframe in accordance with your company/service/platform brand guidelines.

This is an example of a custom form:


API Address: https://sbx-idp.mydexid.org
Endpoint: POST /api/pds HTTP/1.1
Content-Type: application/json
Authentication: hash(SHA512, SHORT-ACCESS-TOKEN + CONNECTION-TOKEN)
Short-Access-Token: SHORT-ACCESS-TOKEN
JSON:

'{    
    "mydexid" : $mydexid,
    "email": $email,
    "password": $password,
    "accept_legal": $accept_legal,
    "api_key": $api_key,
    "connection_nid": $con_id,
    "connection_token_hash": $connection_token_hash,
    "$iframe_style": $iframe_style
    "iframe_content": $iframe_content,
}';
Parameter Description Type Required
mydexid The member MydexID String Y
email The member email address String Y
password The member password String Y
accept_legal The member acceptance of the Mydex Terms, must be ‘TRUE’ for a successful response String Y
api_key Your connection API Key String Y
connection_nid The second number in your Connection ID e.g. 123-4567 String Y
connection_token_hash The SHA512 hash of the connection_token String Y
iframe_style An array containing with one element with the ID “resource”. The value of this element will be the custom CSS you wish to use to style elements in the iframe - this CSS will be appended as a <style> tag in the head of the returned iframe. An example of a json array is the following:
iframe_style":{
  "resource":"body{
    background-color: #D3D3D3;
  } 
  label{
    color: #00FF00
  } 
  .form-control{
    color: blue;
  }"
}
Please note: all strings will be parsed/linted, removing any html/script tags or similar.
Array Optional
iframe_content An array of key => values, where the keys are the IDs of the HTML tags in the iframe, and the values are the content of the html tags.The default array of values used in the PDS Create iframe are the following (in json format):

"iframe_content":{
  "label-access-key":"Private Key:",
  "label-access-key-confirm":"Confirm Private Key:",
  "edit-submit":"Submit",
  "pds-create-ftc-thank-you":"Thank you. PDS was created successfully and you have been successfully connected.A welcome email has been sent.",
  "pds-create-thank-you":"Thank you. PDS was created successfully.A welcome email has been sent.",
  "pds-create-error":"There was an error creating the PDS."
}
When sending the changed values you can omit the ones that do not need changing, and only send the IDs that do need changing.You can also omit this property entirely as it is optional.All strings will be parsed and all tags will be removed with the exception of <b>,<i>,<br>, and <p>
Array Optional

Example response [JSON encoded String]:

"https:\/\/sbx-idp.mydexid.org\/app\/passphrase?token=lwVEMwvmg3HMfKcAURIfQcQ35m%2B3IW5IPFiy5uNOQBI%3D"
Please note: use JSON Decode to parse the iframe URL from the response.

PHP Example

// prepare the array to be posted
$request_data = array(
    'mydexid' => $postdata->mydexid,
    'email' => $postdata->email,
    'password' => $postdata->password,
    'accept_legal' => $postdata->legal,
    'api_key' => $postdata->api_key,
    'connection_nid' => $postdata->connection_nid,
    'connection_token_hash' => hash('SHA512', $connection_token),
    'iframe_expire' => '300',
    'iframe_style' => array(
        'resource' => 'body{background-color: #D3D3D3;} label{color: #00FF00;} .form-control{color: blue;}',
    ),
    'iframe_content' => array(
        'label-access-key' => 'Private Key:',
    ),
);

// compute authentication key based on the previous short access token
$authentication = hash('SHA512', $short_access_token.$connection_token);

$idp_request_url = MYDEX_IDP_PATH . '/api/pds';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $idp_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);

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authentication: 101c88d71c8c979147d71c776ed7a2c453f2f30ba6be0ea96c572fac40d19546fef0480119b4be8469d35c502b5f62004467cf34fe8615a4400ade03ef8ad4ac" -H "Short-Access-Token: E8YomDv2NjRE967XwjuSQmDfmaIhSUCZKWeE+vm+wAA="  -d '{"mydexid": "mymydexid", "email": "email@example.com", "password": "XXX", "accept_legal": "TRUE", "api_key": "XYZ123", "connection_nid": "12345", "connection_token_hash": "ABCD1234", "iframe_style": {"resource":"body{background-color: #D3D3D3;} label{color: #00FF00;} .form-control{color: blue;}"}, "iframe_content": {"label-access-key":"Private Key:"}}' 'API-IDP-URL/api/pds'

Private Key - PDS Create iframe screenshot and markup

The Mydex Private key PDS create iframe markup is built using vanilla Bootstrap (getbootstrap.com). Please see screenshot below and markup available for you to create your own custom CSS. Please note the Submit button will remain in a disabled state (handled via jQuery) until the minimum 8 characters and a matching Private Key is entered.

Please see the Mydex Private Key PDS create iframe markup below - complete with class names available for you to create your custom CSS string.

<body>
  <div class="container-fluid">
    <div class="col-sm-12">
      <div class="row">
        <section>
          <form id="mydex-api-identification" action="" method="post" accept-charset="UTF-8">
            <div class="form-group">
              <label for="edit-access-key" class="control-label">Private Key:</label>
              <div class="mydex-private-key-create" id="mydex-pk-create">Private key valid: <span class="valid error">No</span></div><input type="password" id="edit-access-key" name="access_key" value="" size="15" maxlength="60" class="form-control required">
            </div>
            <div class="form-group">
              <label for="edit-access-key-confirm" class="control-label">Confirm Private Key:</label>
              <div class="mydex-private-key-confirm" id="mydex-pk-confirm">Private keys match: <span class="valid">Yes</span></div><input type="password" id="edit-access-key-confirm" name="access_key_confirm" value="" size="15" maxlength="60" class="form-control required">
            </div>
            <input type="hidden" name="return_to" value="http://api-idp.mixcic.eu/connection-name/verification.php?id=mydexid">
            <input type="hidden" name="token" value="n3JsRT3T6vLN3fYGmxwnIuhLilFTNWJRdy6h6r+8IcQ=">
            <input type="hidden" name="ftc" value="1">
            <div class="form-group clearfix" id="edit-actions">
              <input type="submit" id="edit-submit" name="op" value="Submit" class="btn btn-default pull-right" disabled="disabled">
            </div>
          </form>
        </section>
      </div>
    </div>
  </div>
</body>

By modifying the iframe_style array in step 2 above, the iframe can be styled to fit the connecting organisation's desired display scheme. Below is an example of a modified iframe_style array, followed by the iframe it produces.

Example array:

'iframe_style' => array(
    'resource' => 'body{
        background: url(ABSOLUTE_URL_FOR_BACKGROUND_IMAGE) no-repeat #FAF7EB 95% 5%; 
        padding-top: 40px;
    } 
    label{
        color: #104163;
    } 
    .form-control{
        color: blue;
    }',
),

Styled iframe:

First Time Connection for a memeber with an existing PDS

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

Steps to create a connection for a member with an existing PDS:

  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. Check to see if the member has already set up the connection.
  5. If the connection doesn’t already exist, then using the Mydex API, a short access token should be requested, and then supplied to back to the API when authorising the connection to your organisation.
  6. The returned response will contain an iframe URL for the Mydex Private Key iframe. The member can then enter their Private Key to authenticate and complete the connection to their PDS. This iframe will utilise the optional ‘iframe_style’ string to override the default styles

See the following for a more detailed breakdown of each one...

1. Create a simple login form on your platform

Create a simple HTML form with two input fields to submit the MydexID and Password of the member for authenticating the connection (see example image below).

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

To set up a connection to a PDS a Short Access Token is required to authenticate the API call and return the iframe, which in-turn allows the member to authenticate the connection. Simply POST your organisation’s Connection ID to receive the Short Access Token.

API Address: https://sbx-idp.mydexid.org
Endpoint: POST /access-token/$connection_nid HTTP/1.1

Parameter Description
$connection_nid [String - required] Your organisation’s connection ID provided to you by Mydex when you setup your connection.

Example response [JSON encoded String]:

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

PHP Example

$api_idp_token_url = $api_idp_url . '/access-token/' . $connection_nid;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_idp_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

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

3. Authenticate Member

The first step is to put the member credentials (from step 1) into an authentication array:

$auth_data = array(
  'mydexid' => $mydexid,
  'password' => $password,
  'connection_nid' => $connection_nid,
);

To authenticate the member, a hash value (SHA512) needs to be created using the short access token and connection token e.g.

$authentication = hash('SHA512', $short_access_token.$connection_token);

This hash value should be passed as the authentication in the post to the endpoint, along with the short access token:

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Authentication: ' . $authentication,
  'Short-Access-Token: ' . $short_access_token,
));

Set the json encoded $auth_data in the request using CURLOPT_POSTFIELDS:

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode((object)$auth_data));

Then execute the curl request and check and handle the result. If there is no error, then proceed to the next step.

API Address: https://sbx-api.mydex.org
Endpoint: POST /app/authentication
Content-Type: application/json

Parameter Description
$mydexid [String - required] Value of the MydexID field
$password [String - required] Value of the Password field
$custom_css [String - optional] A string of custom CSS to style elements in the iframe returned - this CSS will be appended as a <style> tag in the head of the returned iframe. An example string: “body{background-color: #D3D3D3;} label{color: #00FF00;} .form-control{color: blue;}”. Please note: all strings will be parsed/linted, removing any html/script tags or similar.

Example response [JSON object]:

{"id":"ID","mydexid":"MYDEXID","email":"EMAIL","created":"TIMESTAMP"} 

4. Check to see if the member has already set up the connection.

This functionality is currently on our development roadmap, along with a range of other ‘developer helper’ functions. Our recommendation in the meantime is that when you initially connect to a member on the Mydex platform, you store the callback information (conn key, member id, etc.) in a local database to use as an internal lookup for determining this.

If the member is not already connected, proceed with steps 5,6, and 7.

5. Get a Short Access Token for Authentication

Since short access tokens can only be used once, request a new one by following the same procedure as in step 2.

The new short access token will be used to request the First Time Connection Iframe URL.

6. Request First Time Connection Iframe (if member not already connected)

The following API call uses the previously acquired short access token. In the table below one can find examples of the labels/content that can be altered in the iframe. Style can be ‘injected’ as well using the ‘iframe_style’ variable in the body of the request.

The API will return an iframe URL which will be embedded on your website after the login form. The iframe will contain an input field for the Private Key which the member will have to fill in. Once the member submits the form inside the iframe they will be prompted with a message whether the connection has been successful or not.

API Address: https://sbx-idp.mydexid.org
Endpoint: POST /api/pds 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_id,
    "connection_token_hash": $connection_token_hash,
    "$iframe_style": $iframe_style
    "iframe_content": $iframe_content,
}';
Parameter Description Type Required
mydexid The member MydexID String Y
api_key Your connection API Key String Y
connection_nid The second number in your Connection ID e.g. 123-4567 String Y
connection_token_hash The SHA512 hash of the connection_token String Y
iframe_style An array containing with one element with the ID “resource”. The value of this element will be the custom CSS you wish to use to style elements in the iframe - this CSS will be appended as a <style> tag in the head of the returned iframe.
An example of a json array is the following:
iframe_style":{
  "resource":"body{
    background-color: #D3D3D3;
  } 
  label{
    color: #00FF00
  } 
  .form-control{
    color: blue;
  }"
}
Please note: all strings will be parsed/linted, removing any html/script tags or similar.
Array Optional
iframe_content An array of key => values, where the keys are the IDs of the HTML tags in the iframe, and the values are the content of the html tags.The default array of values used in the PDS Create iframe are the following (in json format):

"iframe_content":{
  "ftc-access-key":"Private Key:",
  "edit-submit":"Submit",
  "ftc-success-message":"Thank you. The connection has been added successfully.",
  "ftc-error-message":"There was an error connecting with the organization."}
}
When sending the changed values you can omit the ones that do not need changing, and only send the IDs that do need changing.
You can also omit this property entirely as it is optional.
All strings will be parsed and all tags will be removed with the exception of <b>,<i>,<br>, and <p>
Array Optional

Example response [JSON encoded string]:

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

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

PHP Example

// prepare the array to be posted
$request_data = array(
    'mydexid' => $postdata->mydexid,
    'api_key' => $postdata->api_key,
    'connection_nid' => $postdata->connection_nid,
    'connection_token_hash' => hash('SHA512', $connection_token),
    'iframe_expire' => '300',
    'iframe_style' => array(
        'resource' => 'body{background-color: #D3D3D3;} label{color: #00FF00;} .form-control{color: blue;}',
    ),
    'iframe_content' => array(
        'ftc-access-key' => 'Private Key:',
    ),
);

// compute authentication key based on the previous short access token
$authentication = hash('SHA512', $short_access_token.$connection_token);

$idp_request_url = MYDEX_IDP_PATH . '/api/connection';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $idp_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

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","iframe_style":{"resource":"body{background-color: #D3D3D3;} label{color: #00FF00;} .form-control{color: blue;}"},"iframe_content":{"ftc-access-key":"Private Key:"}}' 'API-IDP-URL/api/connection

Private Key - First Time Connection iframe screenshot and markup:

The Mydex Private key - First time connection iframe markup is built using vanilla Bootstrap (getbootstrap.com). Please see screenshot below and markup available for you to create your own custom CSS. Please note the Submit button will remain in a disabled state (handled via jQuery) until the minimum 8 characters and a matching Private Key is entered.

Please see the Mydex Private Key - First Time Connection iframe markup below - complete with class names available for you to create your custom CSS string.

<body>
  <div class="container-fluid">
    <div class="col-sm-12">
      <div class="row">
        <section>
          <form id="mydex-api-identification-connection" accept-charset="UTF-8" method="post" action="">
            <div class="form-group">
              <label id="ftc-access-key" class="control-label" for="edit-access-key"></label>
              <input id="edit-access-key" class="form-control required" type="password" maxlength="60" size="15" value="" name="access_key"></input>
            </div>
            <input type="hidden" value="" name="return_to"></input>
            <input type="hidden" value="g52t6IarhPfqfqtx039gwH5hrKA78s4KTPATVaW3Hd8=" name="token"></input>
            <div id="edit-actions" class="form-group clearfix"></div>
          </form>
        </section>
      </div>
    </div>
  </div>
  <script type="text/javascript"></script>
  <script src="https://js-agent.newrelic.com/nr-476.min.js"></script>
</body>

By modifying the iframe_style array in step 6 above, the iframe can be styled to fit the connecting organisation’s desired display scheme. Below is an example of a modified Iframe_style array, followed by the iframe it produces:

Example array:

'iframe_style' => array(
    'resource' => 'body{
        background: url(ABSOLUTE_URL_FOR_BACKGROUND_IMAGE) no-repeat #FAF7EB 95% 5%; 
        padding-top: 40px;
    } 
    label{
        color: #104163;
    } 
    .form-control{
        color: blue;
    }'
),

Styled iframe: