...
If you have a System Client ID or a Customer System Client ID, then you'll need to follow theClient Credentials Grant workflow to get an access token.
...
You need to provide your access token in this way regardless of which type of client you are using.
Here is anexample call taken from our FHIR documentation, which shows how to use curl to search for a Patient with NHS number 9999999999, assuming you have been granted an access token of aaaaa-bbbbb.
curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer aaaaa-bbbbb" "https://sandbox.patientsknowbest.com/fhir/Patient?identifier=https://fhir.nhs.uk/Id/nhs-number|9999999999"
Token expiry
An access token has a finite lifetime. The number of seconds for which it is valid is indicated by the "expires_in" parameter contained in the response to your token request. This is known as the token duration. Typically, and this is always 1 hour for system clientsfor System Clients, 5 minutes for Customer System Clients, and 10 minutes otherwise.
The session duration is the length of time for which you can keep obtaining new access tokens, using the refresh token, before the granting user must manually re-enter their credentials to renew their grant. Once the session has started (i.e. by the user granting access) it will expire after the session duration, regardless of how many refresh tokens are requested in the meantime. Note that it is possible to set a non-expiring session if that is appropriate for your particular integration. There is no concept of a session for system clientsSystem Clients or Customer System Clients; the Client Credentials Grant workflow will issue an access token but no refresh token.
The table below summarises these scenarios.
Access token lifetime | Detecting expired access token | : custom REST API Session lifetime | Detecting expired | access token: session | ||||||||||
Custom REST API | FHIR API | Session lifetime | Detecting expired session: | Detecting expired session: FHIR API (Facade & Messaging) | FHIR API (Customer & Aggregated) | Custom REST API | FHIR API (Facade & Messaging) | FHIR API (Customer & Aggregated) | ||||||
User Client | 10 minutes | The "errorMessage" string in the returned JSON begins with "access token has expired;" | Error code : | Pending | Configured for your integration | HTTP 401 | Error code : | Pending | ||||||
Tethered-Token System Client | 10 minutes | The "errorMessage" string in the returned JSON begins with "access token has expired;" | Error code : | N/A; Tethered-Token System Clients cannot call the Customer & Aggregated FHIR endpoints | Configured for your integration | HTTP 401 | Error code : | N/A; Tethered-Token System Clients cannot call the Customer & Aggregated FHIR endpoints | ||||||
System Client | 1 hour | N/A; system clients System Clients cannot call the custom Custom REST API | HTTP 401 | N/A; System Clients cannot call the Customer & Aggregated FHIR endpoints | N/A; refresh tokens are not issued to | system clientsSystem Clients | ||||||||
Customer System Client | 5 minutes | N/A; Customer System Clients cannot call the Custom REST API | N/A; refresh tokens are not issued to system clientsCustomer System Clients cannot call the Facade & Messaging FHIR endpoints | HTTP 401 is returned, along with this content: {"message": "JWT is expired"} | N/A; refresh tokens are not issued to | system clientsCustomer System Clients |
X-Org-Public-Id
System Client IDs are used by partners to interact with the PKB APIs on behalf of existing PKB organisations that have chosen to grant access.
...
The UUID will be given to you during setup.
Here is anexample call taken from our FHIR documentation, which shows how to use curl to check whether a document 97a25402-622b-47e0-b650-bbbd08de4daf belonging to org 235a397b-1ae8-4755-9c77-1a0e2fbc5314 has been read by the patient, assuming you have been granted an access token of aaaaa-bbbbb.
curl -X POST --header "Accept: application/fhir+json" --header "Content-Type: application/fhir+json" --header "Authorization: Bearer aaaaa-bbbbb" --header "X-Org-Public-Id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" "https://sandbox.patientsknowbest.com/fhir/DocumentReference/$read-receipt-query" --data "{ \"resourceType\": \"Parameters\", \"parameter\": [ { \"name\": \"documentIdentifier\", \"valueString\": \"97a25402-622b-47e0-b650-bbbd08de4daf\" } ] }"
...