If your client will interact with PKB on behalf of a computer system, rather than a person, then you need to use the Client Credentials Grant workflow.
An example of that scenario would be a hybrid mail provider, making use of our read receipt API.
The organisation you wish to send/receive data for must have granted you authorisation before you will be able to make an API call, but you are able to obtain an access token independently of whether or not any such permissions have been granted.
Note: these examples are written for sandbox.patientsknowbest.com; replace the URL as needed if you are connecting to a different environment.
Request
Description
When you were established as a PKB partner, you will have been issued with a client ID and a client secret. You use these to obtain an access token when you need one.
POST https://oauth2.sandbox.patientsknowbest.com/api/oauth/token
Parameters
Response
Description
PKB responds with the access token in JSON. Note that a refresh token is never provided from a Client Credentials Grant workflow; when your access token expires you can repeat the Client Credentials Grant workflow to obtain a new one.
Parameters
Example
HTTP/1.1 200 OK
{
"access_token":"abcdef",
"token_type":"bearer",
"expires_in":600,
"scope":"none",
"jti":"24eb74c3-ad03-4c4f-a93d-786cf47b6c2f"
}
Error handling
If the authentication fails, then an error will be returned to you.
Example Error
HTTP/1.1 401 Unauthorized
{
"error":"unauthorized"
"error_description":"Full authentication is required to access this resource"
}