Authentication with Your API

To find out which PDS access permissions your users have granted, or to authenticate your users, you need to have your own server listening for HTTPS requests from Mydex.

The Mydex service will make a POST request to your API when a Mydex member initiates a connection or installs an app. Once the connection is initiated or the app is installed, subsequent requests from Mydex are made using PUT to update the data that has already been shared.

What is Sent Along 🔗︎ click to copy

Your REST API should expect the following parameters.

ParameterTypeDescriptionExample
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. 587-99
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:

connection_id=123-3736&uid=1&mydexid=RBFish123&key=CJqVflobLSL6FPAscotDu10QqzHhBFtG&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 url decoded:

connection_id=123-3736 # we're using connection 123-3736 &uid=1 &mydexid=RBFish123 # this pds belongs to this Mydex member &key=CJqVflobLSL6FPAscotDu10QqzHhBFtG # this is our shared key for encryption &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] 0th dataset instance
[a] Access permission (=1for 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/1.json? key=CJqVflobLSL6FPAscotDu10QqzHhBFtG &api_key=cD7FpdDJg5Q5sT0UA3WnmPxNAZwMsVXF &con_id=123-3736 &source_type=connection &dataset=field_ds_personal_details

This is similar to the example API requests made in the 'Personal Data Services' section. The key difference here is that the connection is no longer to the Sandbox server, but to the actual API server at https://api.mydex.org for real user data.


Connection API Details