Personal Data eXchange Overview

By using the Personal Data eXchange API to make a connection to a Personal Data Store of a Mydex member your application and service will be able to send and collect personal data relating to that individual seamlessly over a secure connection to remove the need for form filling and manual data entry. eradicating administration effort and the attending Friction, Effort, Risk and Cost it creates. We call that FERC. The PDX API can dramatically reduce FERC.

This helps the individual to manage their personal data more effectively in a secure and convenient way and streamlines their interactions with your service.

The PDX API enables you to establish a secure and unique connection from your service with an individual's Personal Data Store (PDS), where one already exists. It can also trigger the creation of a MydexID and Personal Data Store as part of a process controlled by you directly e.g. via an app, an email, SMS invitation or a link within an online account the individual holds with the Subscribing organisation.

Your connections can be from your own back office systems, where there is no user interface, or from your own applications or online accounts that the individual you are connecting to uses.

Authenticating to the PDX API 🔗︎ click to copy

OAuth2.0 credentials 🔗︎ click to copy

To access routes on the PDX API (either https://sbx-api.mydex.org for Sandbox or https://api.mydex.org if your connection supports the Live environment), you should authenticate against the PDX API using an OAuth.0 access token, which you obtain from Mydex's OAuth2.0 server using an OAuth2.0 client (using the client_credentials grant).

You can use your OAuth2.0 client credentials to obtain a short-lived access token, which grants you access to routes on the PDX API.

Mydex CIC will supply you with the OAuth2.0 client credentials and scopes when setting up your Dedicated Connection.

OAuth2.0 scopes 🔗︎ click to copy

Your OAuth2.0 client will be carefully scoped to provide access to the routes required.

For all requests to the Mydex PDX API, you must include the scope mydex:pdx when requesting a token. If you are making a request to an individual dataset on the PDX API, thisis the only scope you need when requesting a token.

If you are making use of Mydex's Template System or Feature Blocks, your OAuth2.0 client will also have additional scopes for those purposes. Such scopes reflect the Method and the Endpoint of the request. For example:

This is an abridged list. Mydex will tell you the scopes assigned to your OAuth2.0 client when issuing or updating your OAuth2.0 client.

Remember: even when you are requesting a Template or Feature Block endpoint with an Access Token that is scoped to that Method and Endpoint, the access token must also be scoped to mydex:pdx. If in doubt, just include all scopes, including mydex:pdx, when requesting an OAuth2.0 access token.

If you enter an incorrect scope when requesting the token, you will not receive a token back.

To see examples in Python, PHP and Postman of requesting an OAuth2.0 access token from the Mydex OAuth2.0 server, please visit our Github repository.

OAuth2.0 token lifespan 🔗︎ click to copy

OAuth2.0 access tokens have a lifetime of one hour, after which you must request a new access token.

OAuth2.0 servers 🔗︎ click to copy

Both servers use /oauth2/token as the token endpoint with which to request an OAuth2.0 token using the client_credentials grant.

If you request a route on the PDX API that is not covered by the scope your token is allowed to use, or if your token has expired, you will see this response from the PDX API:

{
  "error": {
    "message": "Access denied",
    "reason": "Unable to authorize the request. Please make sure you send an OAuth2.0 bearer token or an API key."
  }
}

Dedicated Connection NID and Token 🔗︎ click to copy

In addition to OAuth2.0 credentials, you must use your Dedicated Connection NID and Dedicated Connection Token to request a member to consent to you accessing their Personal Data Store. We call this the First Time Connection journey.

To learn how to perform the First Time Connection journey, please click here to continue.

Back: Getting a Dedicated Connection Next: First Time Connection