Skip to main content
Security and authorisation

Learn how we handle security and authorisation for our APIs.

Overview

Many of our APIs give access to sensitive or personal data. This page explains the various techniques or 'patterns' we use to keep them secure.


Security concepts

Systems and users

There are three parties involved in API security:

  • the API itself - more accurately, the system exposing the API

  • the calling application - the system consuming the API

  • the end user - a healthcare worker or a patient, or possibly not present

call API
call API
Calling Application
Calling Applicati...
API
API
do something
do something
OR
OR
call API
call API
Calling Application
Calling Applicati...
API
API
not present
not present
End user
(healthcare worker
or patient)
End user...
End user
End user
Viewer does not support full SVG 1.1 Systems and users context diagram

Authentication and authorisation

Authentication means verifying an identity:

  • user authentication - is the end user who they say they are?

  • system authentication - is the calling application who it says it is?

Authorisation means verifying access rights:

  • user authorisation - is the end user allowed to use that function in the calling application?

  • system authorisation - is the calling application allowed to call that API?

Different APIs use different methods for authentication and authorisation.

call API
call API
Calling Application
Calling Applicati...
API
API
do something
do something
User authentication:
who is it?
User authentication:...
User authorisation: are they allowed?
User authorisation:...
System authentication: who is it?
System authentication...
System authorisation: are they allowed?
System authorisation:...
End user
End user
Viewer does not support full SVG 1.1 Authentication and authorisation context diagram

Assurance

For some of our APIs, we rely on the calling application to handle user authentication and authorisation.

You must do this before we'll allow you to go live. This is part of our onboarding process. We might also ask you to conduct penetration testing to prove your application is secure.

For some of our APIs, we use modern standards to reduce your assurance burden. For example, we use OAuth 2.0 to allow the end user to authenticate directly with us.

Role-based access control (RBAC)

Some of our APIs require you to use role-based access control (RBAC) for user authorisation. RBAC consists of:

  • roles, such as doctor or nurse

  • activities, such as read or update patient demographic details

  • permissions, linking roles to activities

In some cases, we allow you to use your own RBAC system. In other cases, we require you to implement National RBAC - a specific set of roles, activities and permissions defined by us.

For more details, see National RBAC for developers.

Security patterns

Each API uses a security ‘pattern’ appropriate to its needs. The patterns group into three categories:

  • open-access APIs

  • application-restricted APIs

  • user-restricted APIs

The following sections describe the patterns in more detail.

You can find out which security pattern applies to a particular API in the API catalogue.


Open-access APIs

Some of our APIs are open-access, which means:

  • we do not authenticate or authorise the calling application
  • we do not authenticate or authorise the end user - they might not even be present

Here's an illustration:

Calling Application
Calling Applicati...
Open Access
API
Open Access...
do something
do something
OR
OR
Calling Application
Calling Applicati...
Open Access
API
Open Access...
not present
not present
End user
End user
End user
End user
not authenticated
not authorised
not authenticated...
not authenticated
not authorised
not authenticated...
not authenticated
not authorised
not authenticated...
Viewer does not support full SVG 1.1 Open access context diagram


We generally use open-access APIs for public data, where security is not a concern.

Our open-access APIs are generally RESTful APIs. For more details on how to access them, see our open-access REST API tutorial.


Application-restricted APIs

Some of our APIs are application-restricted, which means:

  • we authenticate and authorise the calling application
  • we do not authenticate or authorise the end user

Although we don't authenticate or authorise the end user, for some APIs we do require the calling application to do it 'locally'. For other APIs we don't require the end user to be authenticated or authorised, or even to be present.

Here's an illustration:

Calling Application
Calling Applicati...
Application-Restricted
API
Application-Restr...
authenticated
authorised
authenticated...
not authenticated
not authorised
not authenticated...
OR
OR
Calling Application
Calling Applicati...
Application-Restricted
API
Application-Restr...
authenticated
authorised
authenticated...
not present
not present
Calling Application
Calling Applicati...
Application-Restricted
API
Application-Restr...
authenticated
authorised
authenticated...
locally authenticated
locally authorised
locally authenticated...
OR
OR
Viewer does not support full SVG 1.1 Application-restricted APIs context diagram


We support the following security patterns for application-restricted APIs:

Application-restricted RESTful API - API key authentication

Use this pattern when:

  • accessing an application-restricted RESTful API
  • the API uses API key authentication

In this pattern, you authenticate your application by including an API key with each API request. The API key is unique to your application.

For more details, including detailed technical integration instructions, see Application-restricted RESTful APIs - API key authentication.

Application-restricted RESTful API - signed JWT authentication

Use this pattern when:

  • accessing an application-restricted RESTful API
  • the API uses signed JWT authentication

In this pattern, you authenticate your application by sending a signed JSON Web Token (JWT) to our OAuth 2.0 authorisation server. You provide us with your public key and sign the JWT with your private key. In return, we give you an access token, which you then include with each API request.

This pattern is more secure than API key authentication - we use it for APIs that involve personal or sensitive data.

For more details, including detailed technical integration instructions, see Application-restricted RESTful APIs - signed JWT authentication.

Application-restricted API - TLS-MA authentication

Use this pattern when:

  • accessing an application-restricted API
  • the API uses TLS-MA authentication

In this pattern, we issue you with a TLS-MA certificate that is unique to your application. You authenticate your application by including the TLS-MA certificate with each API request.

We use this pattern for some of our older APIs.

For more details, including detailed technical integration instructions, contact us.


User-restricted APIs

Some of our APIs are user-restricted, which means:

  • we authenticate and authorise the calling application
  • we authenticate, but do not authorise, the end user

Although we don't authorise the end user, we do generally require the calling application to do it ‘locally’.

Here's an illustration:

Calling Application
Calling Applicati...
User-Restricted
API
User-Restricted...
authenticated
authorised
authenticated...
authenticated (by us)
authorised (locally)
authenticated (by us)...
End user
End user
Viewer does not support full SVG 1.1 User-restricted APIs context diagram


We support authentication of healthcare workers using NHS Care Identity Service 2 (NHS CIS2) and patients using NHS login.

We support the following security patterns for user-restricted APIs:

User-restricted RESTful API - using NHS CIS2 - combined authentication and authorisation

Use this pattern when:

  • accessing a user-restricted RESTful API
  • the end user is a healthcare professional
  • you want a simpler integration
  • you don't need the end user's identity information

In this pattern, authentication and authorisation are done together. Authentication is done by NHS CIS2 but we co-ordinate that under the covers behind our OAuth2.0 authorisation server. Your application only needs to be registered with the API Platform, not NHS CIS2.

The end user authenticates with either an NHS smartcard or a more modern alternative. To use smartcards, you need to be connected to the Health and Social Care Network (HSCN).

For more details, including detailed technical integration instructions, see User-restricted RESTful API - NHS CIS2 combined authentication and authorisation.

User-restricted RESTful API - using NHS CIS2 - separate authentication and authorisation

Use this pattern when:

  • accessing a user-restricted RESTful API
  • the end user is a healthcare professional
  • you want to separate authentication from authorisation
  • you need the end user's identity information

In this pattern, authentication and authorisation are done separately. You might authenticate the user when they sign in but only get authorisation to call the API if and when you need it. You do authentication directly with NHS CIS2 and then separately do authorisation with our OAuth2.0 authorisation service. You need to register your application separately with the API Platform and with NHS CIS2.

The end user authenticates with either an NHS smartcard or a more modern alternative. To use smartcards, you need to be connected to the Health and Social Care Network (HSCN).

For more details, including detailed technical integration instructions, see User-restricted RESTful API - NHS CIS2 separate authentication and authorisation.

User-restricted RESTful API - using NHS login - combined authentication and authorisation

Use this pattern when:

  • accessing a user-restricted RESTful API
  • the end user is a patient registered at a GP practice in England, or is receiving NHS services in England
  • you want a simpler integration

In this pattern, authentication and authorisation are done together. Authentication is done by NHS login but we co-ordinate that under the covers behind our OAuth2.0 authorisation server. Your application only needs to be registered with the API Platform, not NHS login.

For more details, see User-restricted RESTful API - NHS login combined authentication and authorisation.

User-restricted RESTful API - using NHS login - separate authentication and authorisation

Use this pattern when:

  • accessing a user-restricted RESTful API
  • the end user is a patient registered at a GP practice in England, or is receiving NHS services in England
  • you want to separate authentication from authorisation

In this pattern, authentication and authorisation are done separately. You can authenticate the user when they sign in but only get authorisation to call the API if and when you need it. You do authentication directly with NHS login and then separately do authorisation with our OAuth2.0 authorisation service. You need to register your application separately with NHS login and with the API Platform.

For more details, including detailed technical integration instructions, see User-restricted RESTful API - NHS login separate authentication and authorisation.

User-restricted HL7 V3 API using NHS CIS2

Use this pattern when:

  • accessing an HL7 V3 API
  • the end user is a healthcare professional

In this pattern, you use NHS CIS2 to authenticate the end user.

NHS CIS2 is an authentication service which:

  • is for healthcare professionals, not patients
  • strongly authenticates the end user, to authentication level AAL3
  • provides a variety of authentication methods, including NHS smartcards, fingerprint recognition on iPad and (coming soon) FIDO2
  • is based on the Open ID Connect open standard
  • is internet-facing - except when used with smartcards

NHS CIS2 can be used in conjunction with our HL7 V3 APIs.

There are some restrictions when using NHS CIS2 with NHS smartcards:

  • the client device must have the Identity Agent and NHS Credential Manager (formerly Identity Hub) components installed, which are only available on Windows
  • the client device must be connected to the Health and Social Care Network (HSCN), though this may change
  • it only supports modern browsers

You can download the latest version of the Identity Agent from Oberthur Smartcard updates.

For more details, including detailed technical integration instructions, see NHS CIS2.

User-restricted HL7 V3 API using CIS

Use this pattern when:

  • accessing an HL7 V3 API
  • the end user is a healthcare professional
  • you already use CIS for authentication and do not want to migrate to NHS CIS2

In this pattern, you use the Care Identity Service (CIS) to authenticate the end user.

CIS is an authentication service which:

You can download the latest version of the Identity Agent from Oberthur Smartcard updates.

For more details on using CIS, see sections 6 and 7 of the Spine External Interface Specification.

Last edited: 6 September 2021 1:28 pm