Authenticating with OAuth2.0
The Mydex MRD API requires authentication using the industry standard OAuth2.0 protocol.
This means that to use the MRD API, Mydex must first have issued you with an OAuth2.0 'client'. This client consists of a Client ID (which you can think of as a 'username' and a Client Secret (analogous to a 'password').
You then make a request to our OAuth2.0 server, using your credentials, to request an 'access token'. If your request is valid, the access token is returned in the response to your request. The access token is short lived with a duration of 3600 seconds (1 hour). After it expires, you can obtain a new token using the same credentials.
OAuth2.0 scopes
The OAuth2.0 client, when created, is 'scoped' to the relevant services or datasets in our MRD that you have subscribed to. To use the ALISS service your OAuth2.0 client must have been granted (at least) the 'aliss' scope by Mydex. It is possible to grant your client access to other service scopes, or to request additional OAuth2.0 clients for other services.
Making a request for an OAuth2.0 token
Your application needs to make a HTTP POST request to our OAuth2.0 service for an access token. This is done using the standard OAuth2.0 protocol/spec with the 'Client Credentials' grant type. You can read more about this Grant Type and the payload/response types here and here.
The OAuth2.0 endpoint is https://op.mydexid.org/oauth2/token
The POST payload body, sent as part of the request using Content-Type: application/x-www-form-urlencoded, must contain the following parameters:
| Name | Value |
| grant_type | client_credentials |
| scope | aliss (at least) - space-separated values if your client supports multiple scopes |
It's important that when listing the scopes in your POST payload, that they are space separated (if your OAuth2.0 client supports multiple scopes). You can, of course, request separate tokens for separate scopes, and use a different token for each different 'service' on the MRD. Or, you can request all the scopes for a request for one token, and use that token for all requests to different services on the MRD.
The request must also use 'HTTP Basic Auth'. This means that a header called 'Authorization' must be present in the request, with the value being 'Basic xxxxxxxxxxxxxxxxxxxxxxxxx', where xxxxxxxxxxxxxxxxxxxxxxxxx is a base64-encoded representation of your OAuth2.0 Client ID and Client Secret, separated by a full colon (:).
Please note: you cannot send the Client ID and Secret as part of the POST payload body alongside the grant_type and scope. This method is referred to as 'client_secret_post' and is considered less secure per the OAuth2.0 spec (please see here for the reasons). Instead, Mydex uses 'client_secret_basic' by default - that is, you send the credentials as a HTTP Basic auth header. If using the HTTP Basic auth method is problematic for your application, please contact us and we will work with you to explore other options.
For example:
if my OAuth2.0 Client ID and Secret were
bf85a12d-59f1-411f-819d-7012c502b76f and 8XTwL3BSkaQpl7P0Jh42KrZrfbGBl7VF9dQyde6X0llCIN4jng2uZWNWEtyqfg9C
then I would need to concatenate these as
bf85a12d-59f1-411f-819d-7012c502b76f:8XTwL3BSkaQpl7P0Jh42KrZrfbGBl7VF9dQyde6X0llCIN4jng2uZWNWEtyqfg9C
and then base64 encode that string, resulting in:
YmY4NWExMmQtNTlmMS00MTFmLTgxOWQtNzAxMmM1MDJiNzZmOjhYVHdMM0JTa2FRcGw3UDBKaDQyS3JacmZiR0JsN1ZGOWRReWRlNlgwbGxDSU40am5nMnVaV05XRXR5cWZnOUM=
I could then send the request with a header
'Authorization: Basic YmY4NWExMmQtNTlmMS00MTFmLTgxOWQtNzAxMmM1MDJiNzZmOjhYVHdMM0JTa2FRcGw3UDBKaDQyS3JacmZiR0JsN1ZGOWRReWRlNlgwbGxDSU40am5nMnVaV05XRXR5cWZnOUM='
Here is an example PHP script that generates the base64 encoding of the credentials:
<?php
$client_id = "bf85a12d-59f1-411f-819d-7012c502b76f";
$client_secret = "8XTwL3BSkaQpl7P0Jh42KrZrfbGBl7VF9dQyde6X0llCIN4jng2uZWNWEtyqfg9C";
$basic_auth = urlencode($client_id) . ':' . urlencode($client_secret);
echo 'Authorization: Basic ' . base64_encode($basic_auth);
Alternatively, if you are constructing your entire HTTP request in PHP, you may find the full example below of more use.
The following demonstrates a full PHP curl request to the OAuth2.0 endpoint with the 'aliss' scope and the credentials above. The function will return an access token which you can then consume in your requests to the MRD API.
<?php
define("OAUTH_TOKEN_ENDPOINT", "https://op.mydexid.org/oauth2/token");
define("OAUTH_MRD_CLIENT_ID", "bf85a12d-59f1-411f-819d-7012c502b76f");
define("OAUTH_MRD_CLIENT_SECRET",
"8XTwL3BSkaQpl7P0Jh42KrZrfbGBl7VF9dQyde6X0llCIN4jng2uZWNWEtyqfg9C");
define("OAUTH_MRD_SCOPES", "aliss");
define("OAUTH_MRD_GRANT_TYPE", "client_credentials");
function request_token() {
// Prepare our POST data's token params
$post_data = [
'grant_type' => OAUTH_MRD_GRANT_TYPE,
'scope' => OAUTH_MRD_SCOPES,
];
// Convert token params to string format
$post_params = http_build_query($post_data, '', '&', PHP_QUERY_RFC1738);
// Content type needs to be form encoded
$content_type = 'application/x-www-form-urlencoded';
$headers[] = "Content-Type: {$content_type}";
// Client ID and Secret are sent as the Authorization (basic) header
$headers[] = 'Authorization: Basic ' . base64_encode(urlencode(OAUTH_MRD_CLIENT_ID) . ':' . urlencode(OAUTH_MRD_CLIENT_SECRET));
// Request a token from the OAuth endpoint
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, OAUTH_TOKEN_ENDPOINT);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_params);
$auth_data = curl_exec($ch);
$auth_data = json_decode($auth_data);
$error = curl_error($ch);
curl_close($ch);
// Did we get a token back?
if (isset($auth_data->access_token)) {
return $auth_data->access_token;
} else {
echo print_r($auth_data, TRUE);
return false;
}
}
Making a request to the MRD API with your OAuth2.0 token
Now that you have an access token from our OAuth2.0 service, you can send it as part of your request to the MRD API.
The Mydex MRD API is available at https://api-mrd.mydex.org. The specific routes for the ALISS service begin with /aliss . Further information on the routes and query parameters available are listed in the 'Search' section further in this document.
Your requests to the MRD API's /aliss need to contain:
- A header called 'Authorization' with the value being 'Bearer: [your OAuth2.0 access token]'
- A header called 'X-Mrd-Scopes', with the value being (at least) 'aliss'. (If you have been granted access to other scopes, requested those other scopes in your OAuth2.0 request, and intend to use this token to access other MRD services that match those scopes, you can also add these as a space-separated or comma-delimited string in this header)
- Here is a PHP example of a curl request to the MRD API's ALISS /get-services/search endpoint, containing a theoretical OAuth2.0 access token defined as variable $token and the X-Mrd-Scopes header still set to 'aliss'.
define("MRD_API_ENDPOINT", "https://api-mrd.mydex.org/aliss/get-services/search");
define("OAUTH_MRD_SCOPES", "aliss");
$params = array('categories' => 'physical-activity');
$url = MRD_API_ENDPOINT . '?' . http_build_query($params);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $token,
'X-Mrd-Scopes: ' . OAUTH_MRD_SCOPES,
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
$mrd_data = curl_exec($ch);
$mrd_data = json_decode($mrd_data);
$error = curl_error($ch);
curl_close($ch);
if (!empty($mrd_data)) {
echo print_r($mrd_data, TRUE);
} else {
echo $error;
}
Putting it all together
Here is a full example PHP script that does the combination of obtaining the OAuth2.0 token and then using it in a request to the MRD. Substitute the Client ID and Client Secret for your own, and it should work.
<?php
define("OAUTH_TOKEN_ENDPOINT", "https://op.mydexid.org/oauth2/token");
define("OAUTH_MRD_CLIENT_ID", "bf85a12d-59f1-411f-819d-7012c502b76f");
define("OAUTH_MRD_CLIENT_SECRET",
"8XTwL3BSkaQpl7P0Jh42KrZrfbGBl7VF9dQyde6X0llCIN4jng2uZWNWEtyqfg9C");
define("OAUTH_MRD_SCOPES", "aliss");
define("OAUTH_MRD_GRANT_TYPE", "client_credentials");
define("MRD_API_ENDPOINT", "https://api-mrd.mydex.org/aliss/get-services/search");
function request_token() {
// Prepare our POST data's token params
$post_data = [
'grant_type' => OAUTH_MRD_GRANT_TYPE,
'scope' => OAUTH_MRD_SCOPES,
];
// Convert token params to string format
$post_params = http_build_query($post_data, '', '&', PHP_QUERY_RFC1738);
// Content type needs to be form encoded
$content_type = 'application/x-www-form-urlencoded';
$headers[] = "Content-Type: {$content_type}";
// Client ID and Secret are sent as the Authorization (basic) header
$headers[] = 'Authorization: Basic ' . base64_encode(urlencode(OAUTH_MRD_CLIENT_ID) . ':' . urlencode(OAUTH_MRD_CLIENT_SECRET));
// Request a token from the OAuth endpoint
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, OAUTH_TOKEN_ENDPOINT);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_params);
$auth_data = curl_exec($ch);
$auth_data = json_decode($auth_data);
$error = curl_error($ch);
curl_close($ch);
// Did we get a token back?
if (isset($auth_data->access_token)) {
return $auth_data->access_token;
} else {
echo print_r($auth_data, TRUE);
return false;
}
}
function request_mrd($token) {
$params = array('categories' => 'physical-activity');
$url = MRD_API_ENDPOINT . '?' . http_build_query($params);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $token,
'X-Mrd-Scopes: ' . OAUTH_MRD_SCOPES,
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
$mrd_data = curl_exec($ch);
$mrd_data = json_decode($mrd_data);
$error = curl_error($ch);
curl_close($ch);
if (!empty($mrd_data)) {
echo print_r($mrd_data, TRUE);
} else {
echo $error;
}
}
echo "Requesting a token\n";
$token = request_token();
if ($token) {
echo "Requesting the MRD with token " . $token . "\n";
request_mrd($token);
}
Example output:
$ php example-aliss-request.php
Requesting a token
Requesting the MRD with token
1nindLlsFMVEXV6a0Tf22qHmipqDcNt42HHO-fFLKFM.YZQd18eqftHmsiwmzUTyjB8pleV9MX0HeGGdDUH6Dmw
Array
(
[0] => stdClass Object
(
[id] => 0016c50e-d178-4ef9-87b4-475f18d8b6fb
[name] => Yoga
[description] => A system of positional exercise to improve all components of fitness and promote overall wellbeing. Please check our website for more information.
[url] => https://www.highlifehighland.com/tracc/all-classes/
[email] => traccleisure@highlifehighland.com
[slug] => yoga-49
[last_updated] => 2019-06-06T08:40:53.917
[phone] => 01862 893767
[categories] => Array
(
[0] => stdClass Object
(
[name] => Physical Activity
[slug] => physical-activity
)
[1] => stdClass Object
(
[name] => Activity
[slug] => activity
)
[2] => stdClass Object
(
[name] => Exercise & Get Fit
[slug] => exercise-get-fit
)
)
[service_areas] => Array
(
)
[locations] => Array
(
[0] => stdClass Object
(
[formatted_address] => Tain Royal Academy, Hartfield Rd, Tain, IV19 1DX
[name] => Tain Royal Academy
[description] =>
[street_address] => Hartfield Rd
[locality] => Tain
[region] =>
[state] =>
[postal_code] => IV19 1DX
[... truncated...]