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.

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

Request

Description

If this flow is appropriate for your integration, 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.

The request must be made as a POST to the token endpoint. The URL of the token endpoint will vary depending on:

The environment you are connecting to (e.g. sandbox, UK production, EU production, etc.)
The API endpoint that you are calling (the Facade and Messaging FHIR endpoints share one token endpoint, which differs from the token endpoint for the Customer and Aggregated FHIR endpoints)

Please see the Connectivity page for details.

Parameters

Parameter	Type	Optionality	Description	Example
grant_type	Form parameter	Required	Must be "client_credentials"	client_credentials
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	Basic ZXhhbXBsZV9jbGllbnRfaWQ6ZXhhbXBsZV9jbGllbnRfc2VjcmV0
Content-Type	HTTP header	Required	Must be "application/x-www-form-urlencoded"	application/x-www-form-urlencoded

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	eyJhbGxxxx
token_type	JSON parameter	Required	This is always "bearer" (case may vary)	bearer
expires_in	JSON parameter	Required	This indicates the number of seconds for which the access_token is valid	600
Other parameters maybe returned (e.g. scope, jti) - you can safely ignore them.

Examples

Facade endpoint

HTTP/1.1 200 OK

{
    "access_token": "abcdef",
    "token_type": "bearer",
    "expires_in": 3599,
    "scope": "4e4a5165-af36-40ec-877a-0333cde24490-all",
    "client_name": "Your client name",
    "jti":"24eb74c3-ad03-4c4f-a93d-786cf47b6c2f"
}

Customer endpoint

HTTP/1.1 200 OK

{
    "access_token": "abcdef",
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "email profile"
}

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

PKB customer sites: deploy | developer | information governance | procurement | manual

This API specification and design is licensed under a Creative Commons Attribution 4.0 International License.