Skip to main content

Security and authorisation

Learn how we handle security and authorisation for our APIs.

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.

We have three types of security in our APIs:

  • open-access
  • application-restricted
  • user-restricted

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

Open-access APIs

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

  • the calling application is not authenticated - we don't care who it is
  • the end user is not authenticated - we don't care who it is - or even whether they are present

Here's an illustration:

Security for open access APIs

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

All our open-access APIs are 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:

  • the calling application is authenticated - we do care who it is
  • the end user is not authenticated - we don't care who it is - or even whether they are present
  • in most cases, API calls are generally encrypted to keep data secure in transit

Here's an illustration:

Security for application-restricted APIs

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:

  • the calling application is authenticated - we do care who it is
  • the end user is authenticated - we do care who it is - and that they are present
  • API calls are encrypted to keep data secure in transit

Here's an illustration:

Security for user-restricted APIs

Currently we only support authentication of healthcare professionals.

In the future we plan to support authentication of citizens using NHS Login.

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

User-restricted RESTful API - using NHS Identity - 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 Identity 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 Identity.

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 Identity combined authentication and authorisation.

User-restricted RESTful API - using NHS Identity - 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 Identity 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 Identity.

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 Identity separate authentication and authorisation.

User-restricted HL7 V3 API using NHS Identity

Use this pattern when:

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

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

NHS Identity is an authentication service which:

  • is for healthcare professionals, not citizens
  • 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 Identity can be used in conjunction with our HL7 V3 APIs.

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

  • the client device must have the Identity Agent and NHS 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

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

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 don’t want to migrate to NHS Identity

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

CIS is an authentication service which:

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

Last edited: 16 October 2020 3:31 pm