Authentication with Your API

To find out which PDS access permissions your members have granted when completing the First Time Connection journey, and to authenticate your requests to the members' PDS for ongoing read/write requests henceforth, you need to have your own server listening for inbound HTTPS requests from Mydex. We call this your Dedicated Connection's 'callback' route.

The Mydex API will make a POST request to your callback when a Mydex member completes the First Time Connection journey to approve your Dedicated Connection's access to their PDS.

Should you request an update to the desired dataset permissions, Mydex updates your Dedicated Connection. The next time a member uses your service, they'll be prompted to re-approve the updated Data Sharing Agreement. When this happens, Mydex makes a request to your callback route again, but as a PUT request to update the member data in your service.

What is Sent Along in the payload to your callback 🔗︎ click to copy

Your REST API for your callback route, should expect the following parameters.

Parameter	Type	Description	Example
`uid`	int	The unique ID of a mydex member	587
`mydexid`	string	The unique MydexID of the member	RBFish123
`key`	string	The shared key (Member Key or Member Connection Key) used to encrypt any information shared between yourself and the member	6nD1a7EATbP7ewmZCpNkxzzyMvuIKqQQ
`connection_id`	string	The connection_id is a shared id between a connection and a member. It is a hyphenated combination of the member UID and the Dedicated Connection NID.	587-4567
`fields`	array	An array of datasets and fields with the member permission for the connection/application. May also include a value attribute containing the data for the field.	See example below

Authentication Header 🔗︎ click to copy

The callback request to your API endpoint after the First Time Connection adds a hashed (SHA512) Connection Key as an HTTP header eg `"Authentication: xxxxxxxxxxxxxxxxxxxxxxx` to the request. This will be the same Key we issued with your Dedicated Connection . You can use this header to check the request was sent from the Mydex PDS API by comparing with your Connection Key (as a SHA512 hash) - eg the two should match.

The Authentication Payload 🔗︎ click to copy

Below is an example of an example authentication payload POSTed to your callback:

connection_id=587-4567&uid=1&mydexid=RBFish123&key=6nD1a7EATbP7ewmZCpNkxzzyMvuIKqQQ&fields%5Bfield_ds_personal_details%5D%5B0%5D%5B%5D%5Baccess%5D%5Br%5D%5Ba%5D=1&fields%5Bfield_ds_personal_details%5D%5B0%5D%5B%5D%5Baccess%5D%5Br%5D%5Bs%5D=A&fields%5Bfield_ds_personal_details%5D%5B0%5D%5B%5D%5Baccess%5D%5Bw%5D%5Ba%5D=1&fields%5Bfield_ds_personal_details%5D%5B0%5D%5B%5D%5Baccess%5D%5Bw%5D%5Bs%5D=A

Reformatted and decoded:

connection_id=587-4567                                    # the connection_id is a combination of the member uid and your dedicated connection_nid
&uid=587                                                  # the uid of the member
&mydexid=RBFish123                      # this pds belongs to this Mydex member
&key=6nD1a7EATbP7ewmZCpNkxzzyMvuIKqQQ                     # this is our shared member key for reading/writing to the member's encrypted PDS
&fields[field_ds_personal_details][0][][access][r][a]=1   # see below
&fields[field_ds_personal_details][0][][access][r][s]=A
&fields[field_ds_personal_details][0][][access][w][a]=1
&fields[field_ds_personal_details][0][][access][w][s]=A

Understanding the Fields Parameters 🔗︎ click to copy

The four fields parameters describe the permissions granted by the user to your connection. A breakdown of the different parts of these parameters and their meanings are given in the following table:

Symbol	Meaning
`[0]`	0^th dataset instance
`[a]`	Access permission (`=1`for permission granted, `=0` for permission denied)
`[s]`	Access style (`=A` when granted automatic permission, `=R` when granted request permission)
`[r]`	When reading data
`[w]`	When writing data

When automatic access permission has been granted, the fields in the member's PDS can be updated without their explicit consent. When request access permission has been granted, it is at the member's discretion to allow your changes to their PDS.

Examples 🔗︎ click to copy

When automatic (A) read and write permission has been granted:

field_ds_personal_details[0][access][r][a] = 1 field_ds_personal_details[0][access][r][s] = A field_ds_personal_details[0][access][w][a] = 1 field_ds_personal_details[0][access][w][s] = A

When request (R) read and write permission has been granted:

field_ds_personal_details[0][access][r][a] = 1 field_ds_personal_details[0][access][r][s] = R field_ds_personal_details[0][access][w][a] = 1 field_ds_personal_details[0][access][w][s] = R

When read and write permission has been revoked:

field_ds_personal_details[0][access][r][a] = 0 field_ds_personal_details[0][access][r][s] = A or R field_ds_personal_details[0][access][w][a] = 0 field_ds_personal_details[0][access][w][s] = A or R

Making Requests Once Authenticated 🔗︎ click to copy

Once the connection is initiated or application installed, the data retrieved can be used to construct API requests.

In this case, if a Subscribing organisation wanted to fetch the latest version of the Personal Details shared with them in the future, they would make an API request that looks like this:

https://api.mydex.org/api/pds/pds/587.json?
    key=6nD1a7EATbP7ewmZCpNkxzzyMvuIKqQQ
    &api_key=cD7FpdDJg5Q5sT0UA3WnmPxNAZwMsVXF
    &con_id=587-4567
    &source_type=connection
    &dataset=field_ds_personal_details

In such a request, the 'key' parameter is the member encryption key, and the con_id is the same value of 'connection_id' received in the callback.

Connection API Details