First Time Connection and Update

Scenario 1: First Time Connection 🔗︎ click to copy

To begin this flow, you should offer a button on your application to 'Get Connected'. Submitting this button should perform a POST request to the Mydex API (described below), at which point you can redirect the member to the URL that is returned from the POST request. Alternatively, you could make your page automatically trigger the POST request to the Mydex API when it loads, and redirect the member immediately.

POST payload details 🔗︎ click to copy

API endpoint: https://api.mydex.org/ftc/setup (use https://sbx-api.mydex.org/ftc/setup for Sandbox)

Mandatory POST body payload parameters:

  "connection_nid": DEDICATED_CONNECTION_NID
  "connection_token_hash": SHA512_HASH_OF_DEDICATED_CONNECTION_TOKEN
  "return_to": "https://example.com" # URL to return to after accepting the DSSA

Optional POST body payload parameters:

If your application has already stepped through an OpenIDConnect (OIDC) login flow with the member and has learned their mydexid as a claim from the UserInfo endpoint, you can optionally pass the mydexid in the payload above.

This has the effect of offering a registration screen in the next step. If the member is still logged in, they will be automatically taken onward to the DSSA page. If they are not logged in, they must enter this same mydexid and their password at the next step.

  "mydexid": {mydexid}

Hint: if you are enrolled to perform OpenIDConnect (OIDC) flows in your application, and have not yet logged the member in, you can put your application's URL that would initiate an OIDC login flow as the return_to value. This will ensure your application learns the member's MydexID after FTC and you can then establish a logged in session for a more seamless experience. Click here to learn more about enrolling to Mydex OIDC Identity as a Service.

Headers to send 🔗︎ click to copy

Authorization: Bearer {oauth_access_token} (scoped to mydex:pdx)

Content-Type: application/json

Response details 🔗︎ click to copy

The Mydex API will return the following details:

Response Code: 201

JSON body:

{
  'qr': 'data:image/png;base64,[.......],
  'url': 'https://login.mydexid.org/ftc/begin/xxxx/xxxxxxxxxxxxxxxxxxxx[...]',
}

You can either redirect the member straight to that URL from the response, or optionally (depending on your need) you could display the QR code for the member to scan (if the FTC journey should take place via a mobile device, for example).

Please note that this URL can only be visited once. If the member tries to refresh the page or revisit it, they will get an error, and will need to step through your first step on your application again to receive a new URL.

Potential error responses 🔗︎ click to copy

The Mydex API may return the following 4XX errors if there is a problem with your request:

Incorrect Dedicated Connection NID

{'error': {'message': 'Access Denied: No Connection record'}}

Incorrect Dedicated Connection Token SHA512 hash

{'error': {'message': 'Access Denied: Invalid Connection Token'}}

Missing mandatory parameters

Error varies depending on what is missing. Examples:

{"error":{"message":"Access Denied: Missing connection parameters in payload"}}
{"error":{"message":"Following fields are missing or empty: return_to"}}

What happens next 🔗︎ click to copy

The member either logs in or registers at MydexID. They are then taken to the Data Sharing and Services Agreement (DSSA) page, where they may review the permissions your Dedicated Connection is requesting.

This is what they will see on the DSSA page:

If the member consents, they enter their Private Key on the DSSA form, and a link is formed between their PDS and your Dedicated Connection.

The Mydex PDX API sends a POST request to your Dedicated Connection callback API endpoint (which you provided Mydex when requesting your Dedicated Connection), containing unique credentials that let you access those allowed parts of the member's PDS. This payload is not sent via the member's browser, it is a server-to-server backend transaction between the Mydex PDX API and your application API. You should consume those credentials in your backend, so that you can use them to construct subsequent requests to the member's PDS via the PDX API

Click here to read how to understand and consume those credentials.

Web Sequence Diagram of First Time Connection Flow 🔗︎ click to copy

The diagram below demonstrates the flow described above. Please click on the image to see a larger version.

Example code 🔗︎ click to copy

Click here to view the example code in Python, PHP or Postman.

Scenario 2: Updating the Connection to the member's PDS 🔗︎ click to copy

In this scenario, the member is already connected, but your Dedicated Connection has been updated (per an agreed arrangement between you and Mydex) to seek access to new or changed datasets and features in the member's PDS.

Because of the change in desired permissions, you must re-request approval from the member to access those new elements of their PDS.

To perform this flow, you must know their MydexID in advance. A common scenario for Subscribers is to store the 'version' of the connection that the member's PDS is using, in your backend (alongside the member's mydexid, member UID and Member Connection Key). You can then use this information to selectively initiate the FTC 'update' flow for members who are on an older version.

Such a detection is commonly performed when the member next logs into your application using OIDC (at which point you learn their mydexid as a UserInfo claim, and can check this against your records in your backend). Use of OIDC is not strictly required, but knowing their MydexID is in order to initiate the flow.

The process of initiating the FTC Update flow is almost identical to Scenario 1, except that there are some additional parameters in the POST payload:

POST payload details 🔗︎ click to copy

API endpoint: https://api.mydex.org/ftc/setup (use https://sbx-api.mydex.org/ftc/setup for Sandbox)

Mandatory POST body payload parameters:

  "connection_nid": DEDICATED_CONNECTION_NID
  "connection_token_hash": SHA512_HASH_OF_DEDICATED_CONNECTION_TOKEN
  "return_to": "https://example.com" # URL to return to after accepting the DSSA
  "mydexid": {mydexid}, # e.g. johncitizen
  "version": {version} # e.g "2"

Headers to send 🔗︎ click to copy

Authorization: Bearer {oauth_access_token} (scoped to mydex:pdx)

Content-Type: application/json

Response details 🔗︎ click to copy

The Mydex API will return the following details:

Response Code: 201

JSON body:

{
  'qr': 'data:image/png;base64,[.......],
  'url': 'https://login.mydexid.org/ftc/begin/xxxx/xxxxxxxxxxxxxxxxxxxx[...]',
}

You can either redirect the member straight to that URL from the response, or optionally (depending on your need) you could display the QR code for the member to scan (if the FTC journey should take place via a mobile device, for example).

Please note that this URL can only be visited once. If the member tries to refresh the page or revisit it, they will get an error, and will need to step through your first step on your application again to receive a new URL.

Potential error responses 🔗︎ click to copy

The Mydex API may return the following 4XX errors if there is a problem with your request:

Incorrect Dedicated Connection NID

{'error': {'message': 'Access Denied: No Connection record'}}

Incorrect Dedicated Connection Token SHA512 hash

{'error': {'message': 'Access Denied: Invalid Connection Token'}}

Missing mandatory parameters

Error varies depending on what is missing. Examples:

{"error":{"message":"Access Denied: Missing connection parameters in payload"}}
{"error":{"message":"Following fields are missing or empty: return_to"}}

Missing mydexid

{"error":{"message":"version higher than 1 but no mydexid in payload"}}

Invalid version number

{"error":{"message":"version cannot be lower than 1"}}

What happens next 🔗︎ click to copy

The member is presented with the Login form on the Mydex Login and Consent App (LaCa). They must login with the matching MydexID that was sent in the payload above, otherwise they will receive an error stating that the one-time link was intended for a different MydexID.

If the member was already logged in via OIDC with the correct MydexID prior to clicking the link, they will not see the login screen and will be taken straight away to the Data Sharing and Services Agreement (DSSA) page, where they may review the updated permissions your Dedicated Connection is requesting.

The version parameter will ensure that only the new (updated) permissions will be shown on the DSSA form, making it clear what changes the member is being asked to consent to.

If the member consents, they enter their Private Key on the DSSA form, and a link is formed between their PDS and your Dedicated Connection.

In the Update flow, the Mydex PDX API sends a PUT request to your Dedicated Connection callback API endpoint (which you provided Mydex when requesting your Dedicated Connection), containing updated permission details about your access to the member's PDS. This payload is not sent via the member's browser, it is a server-to-server backend transaction between the Mydex PDX API and your application API. Unlike in the First Time Connection flow, the member connection key is not re-sent in the Update flow. You should consume the payload in your backend as fits your application needs.

Click here to read how to understand and consume those credentials.

Web Sequence Diagram of Update Flow 🔗︎ click to copy

The diagram below demonstrates the flow described above. Please click on the image to see a larger version.

Example code 🔗︎ click to copy

Click here to view the example code in Python, PHP or Postman.