First Time Connection and Update

You may have your own Identity/Membership stack and an existing member base 🔗︎ click to copy

You may already be operating your own identity stack for registration and authentication to your site or application.

In this scenario, when you request the FTC one-time URL from Mydex to provide to your Member, you should send the parameter linking_token with a unique attribute that represents the member in your backend.

Mydex will take charge of offering the member either Registration/Provisioning or Login of their MydexID and PDS at the next step.

When POSTing the member credentials to your Dedicated Connection callback API endpoint, Mydex will ensure that it sends the linking_token attribute alongside the MydexID and Member key credentials, so that you can map them to your unique member attribute.

If your member is revisiting your service and you need to send data to their PDS again, you may first need to determine what their MydexID is in order to check for MydexID and PDS credentials from the previous First Time Connection in your backend. To do this, you can first use the /identify route to be sent the member's MydexID to your callback, and from there, you can decide whether to send the member through First Time Connection or not.

You may be delegating authentication to a 3rd party Identity Provider (Google, Facebook, etc.) 🔗︎ click to copy

You no doubt still map the third party Identity Provider's member attribute to your backend in order to present a personalised experience in your application for the member. You will need to map the member's MydexID/PDS to that third party attribute in your backend after First Time Connection has completed.

In this scenario, when you request the FTC one-time URL from Mydex to provide to your Member, you should send the parameter linking_token with a unique attribute that represents the member in your backend.

Mydex will take charge of offering the member either Registration/Provisioning or Login of their MydexID and PDS at the next step.

When POSTing the member credentials to your Dedicated Connection Callback API endpoint, Mydex will ensure that it sends the linking_token attribute alongside the MydexID and Member key credentials, so that you can map them to your unique member attribute.

If your member is revisiting your service and you need to send data to their PDS again, you may first need to determine what their MydexID is in order to check for MydexID and PDS credentials from the previous First Time Connection in your backend. To do this, you can first use the /identify route to be sent the member's MydexID to your callback, and from there, you can decide whether to send the member through First Time Connection or not.

You are using Mydex's Identity as a Service (IDaaS) to let the member register and login with their MydexID 🔗︎ click to copy

Mydex offers OpenIDConnect (OIDC) with the MydexID acting as the member attribute. If your application is capable of acting as an OIDC Relying Party (RP), Mydex can issue you with OIDC credentials (separate from your PDX API OAuth2.0 client) and you can use them to delegate authentication to Mydex entirely. You can use OIDC to Register or Login an existing MydexID. Please read more about Mydex Identity as a Service here.

In this scenario, when you request the FTC one-time URL from Mydex to provide to your Member, you should send the parameter mydexid with the MydexID (which you have learned as a standard OIDC claim after the member registered or signed in to your service with their MydexID).

Doing so ensures that the member isn't presented with a Registration screen on the FTC journey, and it also means you can associate the member with the PDS credentials that are POSTed to your Dedicated Connection Callback API endpoint after FTC completes (which also contains the matching mydexid in that payload).

You do not need any form of sign-in or registration service and just need to send collected data to a PDS 🔗︎ click to copy

Your application may provide a service that collects information from the Member (e.g via the form of a survey, questionnaire or other type of form). There may not need to be any registration or login journey in your application complete this process. At the end of the journey, you might be inviting the member to connect their MydexID and PDS in order for you to transmit the collected data into their PDS.

Mydex can easily accommodate this: a First Time Connection can be achieved with a Member's MydexID and PDS via a one-time URL. You would store the credentials received in the FTC callback so that you can transmit the data to their PDS.

If your member is revisiting your service to undertake another journey, and you need to send data to their PDS again, you may first need to determine what their MydexID is in order to check your backend system for MydexID and PDS credentials from the previous First Time Connection. To do this, you can first use the /identify route to be sent the member's MydexID to your callback, and from there, you can decide whether to send the member through First Time Connection (if you found no such records) or else just use the previously recorded credentials to send new data to their PDS again.

To achieve this flow, you will request the FTC one-time URL from Mydex with just the mandatory parameters and redirect the member to the one-time URL. Mydex will take care of offering the member either Registration or Login of their MydexID at the next step. You will consume the PDS credentials that are POSTed to your Dedicated Connection Callback API endpoint after FTC completes and you can use them to make requests to the member's Personal Data Store.

You do not run any frontend app and just want to send data to a PDS via periodic or event-driven backend requests 🔗︎ click to copy

Your application may not have any frontend component at all and operates purely as a back-end solution. Examples might be 'Internet of Things' devices such as smart home meters that need to transmit energy data to the member's PDS without needing any frontend app or the member's presence to do so. Mydex can easily accommodate this: a First Time Connection can be achieved with a Member's MydexID and PDS via a one-time URL.

To achieve this flow, you will request the FTC one-time URL from Mydex with just the mandatory parameters. Mydex will take care of offering the member either Registration or Login of their MydexID at the next step. You will consume the PDS credentials that are POSTed to your Dedicated Connection Callback API endpoint after FTC completes and you can use them to make requests to the member's Personal Data Store.

You will need to send this one-time URL to the potential member via a means that makes sense to you (for example, via e-mail as an invitation to 'get started', a messaging app or by using the QR code on a card and handing it out at an event).

What is needed to get started? 🔗︎ click to copy

In all cases, a Subscriber needs three things to start the First Time Connection Journey:

• A Dedicated Connection at Mydex, which they can request on the Mydex Connection Manager. Please read Getting a Dedicated Connection for more information.
• OAuth2.0 credentials, issued by Mydex at the same time as the Dedicated Connection credentials, in order to authenticate to the PDX API. Please see here for more information on OAuth2.0
• A HTTPS endpoint that Mydex can make POST requests to when a Member consents to the Data Sharing Agreement with the Subscriber's Dedicated Connection. This endpoint will be used to send a payload of credentials about the member and their PDS that let you access their PDS via the PDX API henceforth. Please see here for more information on this payload.

In all cases, a Member needs two things, both of which are free to them for life:

• A MydexID (like a username)
• A Personal Data Store (this is automatically provisioned and linked to the MydexID when they register one)

Regardless of your scenario, Mydex offers a holistic solution for Subscribers to trigger a seamless flow via a single request which will let the member register a MydexID and Personal Data Store, or login with their existing MydexID, in order to approve the Data Sharing Agreement and get connected to your service.

Technical Steps to Identify the member's MydexID (if not using Mydex IDaaS) 🔗︎ click to copy

Before you begin

If you are operating a service whereby the member may have already completed First Time Connection on a previous visit, but has returned to your service to use it again, you will have consumed those member PDS credentials from the First Time Connection callback (described in the sections below). However, you may need to 'identify' the returning member by their MydexID in order to look up those credentials in order to use their PDS again.

In many cases, a Subscriber will be operating their own Identity Service and so will have already 'mapped' the MydexID and PDS credentials returned from the callback, to their existing member object in their system.

In other cases, the Subscriber will be using Mydex's Identity as a Service, which means the mydexid is learned as an OIDC claim after logging into the service each time.

However, in some cases the Subscriber has no Identity Service at all, but still needs to identify the member's MydexID in order to use their PDS. In many cases this step happens at the conclusion of some other process, for example, filling out a survey or creating a document, and now it needs to be sent to the member's PDS.

To handle this scenario, Subscribers can make use of the /identify endpoint. This will delegate login of the Member to Mydex's Login and Consent Application, and will send the member's mydexid to the Subscriber's Dedicated Connection callback API endpoint (the same one that also receives First Time Connection payloads). Your application can then check your own records for that mydexid to find the matching PDS credentials (if the member had previously completed FTC in a prior visit), or (if no such record is found), commence the FTC journey via /ftc/setup (per the instructions in the sections below).

In this section we explain how to use the /identify endpoint to learn the Member's MydexID without needing to operate an Identity Service or use Mydex's Identity as a Service.

POST payload details 🔗︎ click to copy

API endpoint: https://api.mydex.org/identify (use https://sbx-api.mydex.org/identify 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 Member logs in

Optional POST body payload parameters:

• linking_token - If you need to associate the MydexID to the member's data record in your system, or are operating your own, or a third party Identity platform, and you wish to map the member's PDS details to this attribute, pass a unique attribute representing the member from your system here. This will be included in the POST callback to your Dedicated Connection Callback API endpoint as linking_token so you can map it to that member in your system. The member will also be returned to your return_to endpoint with the ?linking_token query parameter appended, in case that helps with their frontend experience.

Hint: if you have no frontend application and are operating a purely back-end service, we recommend to put https://my.mydex.org as the return_to value. Use https://sbx-my.mydex.org if you are operating in the Sandbox Environment.

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/identify/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 Identify journey should take place via a mobile device, which may be useful when the return_to URL needs to be a 'deep link' to a native application on the device after FTC takes place).

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. The URL is valid for 24 hours or until it is first used.

What happens next for the Member 🔗︎ click to copy

The member either logs in or registers a MydexID and PDS on the Mydex Login and Consent app.

They are then redirected back to your return_to URL.

What happens next for the Subscriber 🔗︎ click to copy

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 the following payload:

{
  "type": "identify",
  "mydexid": "johncitizen",
  "linking_token": "xxxxxxxxxxxxxxx" # if you specified one in the /identify payload
}

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 can use the payload to search for the mydexid in your system to see if this member is a returning visitor who had previously completed the FTC flow. If you find such records, you now have everything you need to interact with their PDS.

If you don't find such a record, this is your indication that you need to send the member on the /ftc/setup journey. Since you now know what the mydexid is, you can include it in the payload when requesting the /ftc/setup endpoint, which will help the member automatically step through the login flow and return to the Data Sharing and Services Agreement (DSSA) page to complete FTC.

Please note: we recommend that you use the linking_token attribute so that you can align the payload you received out-of-band from the Mydex PDX API, with the request that the member made by following the one-time /identify URL. This could be a row ID of some (even temporarily) saved record, a cookie ID to match against the member's session, a unique hash of a file, or some other unique attribute that can be associated with whatever action the member took on your application prior to beginning the Identification process. This will ensure that you are sending the correct data to the correct PDS. You can use the same linking_token in your payload to the /ftc/setup endpoint if you need to send the member on to FTC, to associate in the same way.

Web Sequence Diagram of Identification 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.

Technical Steps to achieve First Time Connection 🔗︎ click to copy

Before you begin

Design Considerations for Member UX 🔗︎ click to copy

To begin this flow, Mydex recommends offering a button on your application to 'Get Connected with Mydex' or 'Connect your Mydex Personal Data Store'. Submitting this button should perform a POST request to the Mydex API (described below), at which point you can redirect the member to the one-time 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. However, this may lead to unnecessary one-time links created if others (or bots) visit the page.

Please note: The one-time URL is capable of offering both Registration of a MydexID/PDS and Login (existing MydexIDs), depending on need, so there is no need to present two separate buttons.

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 Member accepts your DSSA

Optional POST body payload parameters:

• mydexid - 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, or you have learned it via the /identify flow described in the section above, you can optionally pass the mydexid in the payload above. This has the effect of skipping the registration option 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.
• linking_token - If you are operating your own, or a third party Identity platform, and you wish to map the member's PDS details to this attribute, pass a unique attribute representing the member from your system here. This will be included in the POST callback to your Dedicated Connection Callback API endpoint as linking_token so you can map it to that member in your system.

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.

Hint: if you have no frontend application and are operating a purely back-end service, we recommend to put https://my.mydex.org as the return_to value. Use https://sbx-my.mydex.org if you are operating in the Sandbox Environment.

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. The URL is valid for 24 hours or until it is first visited.

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 for the Member 🔗︎ click to copy

The member either logs in or registers a MydexID (depending on whether you knew of and passed the mydexid in the /ftc/setup request).

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.

What happens next for the Subscriber 🔗︎ click to copy

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 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 securely. It is these credentials that you use to construct subsequent requests to the member's PDS via the PDX API, along with your PDX API OAuth2.0 client.

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.

Requesting re-approval/updating of the Connection to the member's PDS if they are already connected 🔗︎ 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 in order to have identified that a re-approval is needed to update them to the latest version of your Dedicated Connection. You can learn the MydexID either by operating as an OIDC Relying Party with Mydex's IDaaS, or use the /identify flow to delegate login to Mydex and be sent the MydexID in a callback payload to your Dedicated Connection callback API endpoint.

How do I know what version of my Dedicated Connection the Member is on? 🔗︎ click to copy

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.

If you have not stored the 'version' of the member's connection in your backend when they performed First Time Connection, you can still check this at the Mydex PDX API.. To do this, visit:

https://api.mydex.org/connection/status/{con_nid}?uid={uid}&con_id={con_id}

Where con_nid is the Dedicated Connection to check the status of, the uid is the numerical UID of the Member, and con_id is your Dedicated Connection ID (combination of the Member UID and the Connection NID).

Required headers 🔗︎ click to copy

• Connection-Token: {Member's Connection Key from your backend}
• Authorization: Bearer {oauth2_access_token} (scoped to mydex:pdx)
• Content-Type: application/json

Response 🔗︎ click to copy

If the Member still has your connection active in their PDS, the response will be:

{
  "exists": "true",
  "status:" "true",
  "version: "1"
}

If you get Permission Denied or 'false' values in the response, then the connection is not active and you can take the member through FTC.

POST payload details for Updating a Connection to a Member's PDS 🔗︎ 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 Member accepts your DSSA
  "mydexid": {mydexid}, # e.g. johncitizen
  "version": {version} # e.g "2"

Hint: if you have no frontend application and are operating a purely back-end service, we recommoend to put https://my.mydex.org as the return_to value. Use https://sbx-my.mydex.org if you are operating in the Sandbox Environment.

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 for the Member 🔗︎ 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.

What happens next for the Subscriber 🔗︎ click to copy

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.