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.

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 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

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 (=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

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 an 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 'Getting Started' 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