Client credentials


Client Credentials Grant

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.

Client uses client ID and client secret to obtain an access token

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.

HTTP Verb POST
URL https://oauth2.sandbox.patientsknowbest.com/api/oauth/token

Parameters

Parameter Type Optionality Description Example
Authorization HTTP header Required This is a standard HTTP basic authorization header.

The value should be a Base64 encoding of your client ID and client secret, concatenated together with a colon (:) separator, and prepended with "Basic ".

For example, if your client ID was example_client_id and your client secret was example_secret then your header value should be:

Basic ZXhhbXBsZV9jbGllbnRfaWQ6ZXhhbXBsZV9jbGllbnRfc2VjcmV0
ZXhhbXBsZV9jbGllbnRfaWQ6ZXhhbXBsZV9jbGllbnRfc2VjcmV0
grant_type Form parameter Required Must be "client_credentials" client_credentials

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

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 abcdef
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
scope JSON parameter Required Currently, scopes are not supported. As such, this will always be "none". none
jti JSON parameter Required A unique identifier for this token. 24eb74c3-ad03-4c4f-a93d-786cf47b6c2f


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"
}

Comments