If your client needs to obtain authorization from an existing PKB user in order to interact with the PKB APIs on behalf of that user, then you need to use the Authorization Code Grant workflow.
An example of that scenario would be a mobile app for patients, which allows a patient to grant access to their existing PKB account.
Note: these examples are written for sandbox.patientsknowbest.com; replace the URL as needed if you are connecting to a different environment.
Description
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
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
Error handling
If there's a problem with the request, PKB will show an error page in the browser.
Description
In response to the request made in the previous step, PKB will show an authorization page. This will state which client is asking for access (the owner and product name), and prompt the user to enter their credentials if they wish to grant access to the client.
The user will either do this and click "Approve", or they can click "Deny".
If the user clicks "Approve" and the authentication is successful, PKB will generate an Authorization Code. This will be passed back to the client as a URL parameter whilst redirecting the user to the specified redirect_uri. If a redirect_uri was not specified then the single redirect URI already known to be associated with the Client ID will be used.
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
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.
https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=ANTI_CSRF_12345
Error handling
If user clicks "Deny" (or if the authentication fails, or there is another error), then the redirect will include an "error" parameter instead of the "code" parameter.
See section 4.1.2.1 for more information on error codes.
Example Error
An example redirect is shown below.
https://client.example.com/cb?error=access_denied&state=ANTI_CSRF_12345
Request
Description
Once you have an authorization code, you can swap this for an access token (and possibly a refresh token too).
POST https://sandbox.patientsknowbest.com/apiToken.action
Parameters
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).
https://sandbox.patientsknowbest.com/apiToken.action?grant_type=authorization_code&client_id=myClientId&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https://client.example.com/cb
Response
Description
PKB responds with the access token in JSON, and possibly a refresh token too.
Parameters
Example
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"
}
Error handling
The authorization code is only valid for 10 minutes. If that duration expires, or if another occurrs, then an error response is returned.
See section 5.2 for a full list of error response codes.
Example Error
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error":"invalid_request"
}
Request
Description
An access token is only valid for a short duration (normally 10 minutes). After that, a new access token can be requested using a refresh token. This will be possible until the session expires (unless your Client ID is configured to have non-expiring sessions).
Refresh tokens can only be used once. If one is submitted that has previously been used, all active tokens for that session will be revoked.
POST https://sandbox.patientsknowbest.com/apiToken.action
Parameters
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).
https://sandbox.patientsknowbest.com/apiToken.action?grant_type=refresh_token&client_id=myClientId&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&scope=PATIENT
Response
Description
PKB responds with a new access token in JSON, and possibly a refresh token too (if the session hasn't expired).
Example
Same as for the initial token request above.
Error handling
Same as for the initial token request above.