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
Your REST API 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. | 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
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
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
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 (=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
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
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.