...
Note: these examples are written for http://sandbox.patientsknowbest.com ; replace the URL as needed if you are connecting to a different environment.
...
The client should generate a URL as follows, and then send the user to that URL in a browser.
GET https://sandbox.patientsknowbest.com/apiAuthorize.action
Parameters
Parameter | Type | Optionality | Description | Example |
response_type | Query parameter | Required | Must be "code" | code |
client_id | Query parameter | Required | The REST API Client ID previously issued to you | myClientId |
scope | Query parameter | Optional | Allowed values are:
If a value is not provided, we will permit a user from any scope that has has been enabled for your REST API Client ID. | PATIENT |
state | Query parameter | Optional | Although this is optional, it is strongly recommended . This should be an opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery, as described in Section 10.12 . | ANTI_CSRF_12345 |
redirect_uri | Query parameter | Conditional | If you have several redirect URIs registered against your Client ID, then you must specify this parameter. Otherwise, it is optional. If you do specify this parameter, you can add additional parameters to the URI on top of the base URI that is associated with your Client ID. Note that we do support localhost addresses and custom URL schemes for mobile apps. You are not able to specify a new URI with this parameter. |
Example
An example of a complete URL is shown below.
https://sandbox.patientsknowbest.com/apiAuthorize.action?response_type= code&client_id=myClientId&redirect_uri=https://client.example.com/cb&scope=PATIENT&state=ANTI_CSRF_12345
...
Note: the authorization code is bound to the Client ID and the redirection URI; the client will need to use the same redirection URI for the next step as well.
Parameters
Parameter | Type | Optionality | Description | Example |
code | Query parameter | Required | The authorization code that can subsequently be used to obtain an access token | SplxlOBeZQQYbYS6WxSbIA |
state | Query parameter | Optional | The same value that was sent in the request, if present | ANTI_CSRF_12345 |
Example
An example redirect is shown below. Note that the authorization code is provided as the "code" parameter, and the "state" parameter provided by the client in the intial request is also appended to the URL.
...
POST https://sandbox.patientsknowbest.com/apiToken.action
Parameters
Parameter | Type | Optionality | Description | Example |
grant_type | Form parameter | Required | Must be "authorization_code" | authorization_code |
client_id | Form parameter | Required | The REST API Client ID previously issued to you | myClientId |
code | Form parameter | Required | The authorization code returned in the previous step | SplxlOBeZQQYbYS6WxSbIA |
redirect_uri | Form parameter | Conditional | If you specified one in the original request, this must match exactly. Otherwise, this is optional. | |
Content-Type | HTTP header | Required | Must be "application/x-www-form-urlencoded" | application/x-www-form-urlencoded |
Example
An example of a complete URL is shown below (parameters are shown in the URL for convenience, but implementations should send them in the body of the POST).
...
PKB responds with the access token in JSON, and possibly a refresh token too.
Parameters
Parameter | Type | Optionality | Description | Example |
access_token | JSON parameter | Required | This is the access token that can subsequently be used to authenticate against the relevant API, and gain access to the functionality | 2YotnFZFEjr1zCsicMWpAA |
token_type | JSON parameter | Required | This is always "Bearer" | Bearer |
expires_in | JSON parameter | Required | This indicates the number of seconds for which the access_token is valid | 600 |
refresh_token | JSON parameter | Optional | If the session has not expired, a refresh_token will also be issued. This can be used to obtain a new access_token when the token validity period has expired. | tGzv3JOkF0XG5Qx2TlKWIA |
scope | JSON parameter | Optional | This will match the scope specified in step 1 | PATIENT |
Example
| Code Block |
|---|
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"Bearer",
"expires_in":600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"scope":"patient"
} |
...
POST https://sandbox.patientsknowbest.com/apiToken.action
Parameters
Parameter | Type | Optionality | Description | Example |
grant_type | Form parameter | Required | Must be "refresh_token" | refresh_token |
client_id | Form parameter | Required | The REST API Client ID previously issued to you | myClientId |
refresh_token | Form parameter | Required | The refresh token issued at the same time as the most recently valid access token | tGzv3JOkF0XG5Qx2TlKWIA |
scope | Form parameter | Optional | The scope of the session | PATIENT |
Example
An example of a complete URL is shown below (parameters are shown in the URL for convenience, but implementations should send them in the body of the POST).
...
PKB customer sites:deploy |developer |information governance |procurement |manual
...