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 use three types of security pattern in the APIs we produce and manage.

  • 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

Open-access APIs generally give access to public data.

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
  • API calls are generally encrypted to keep data secure in transit

Here's an illustration:

Security for application-restricted APIs

Details of application-restricted API security patterns are coming soon.

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 generally 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

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 following diagram illustrates the pattern:

User-restricted RESTful API - combined authentication and authorisation

The following sequence diagram shows how the various components interact:

User-restricted RESTful API - combined authentication and authorisation - sequence diagram

In words:

  1. The end user launches the calling application.
  2. The calling application redirects the user's browser to our OAuth2.0 authorisation endpoint (/oauth/authorize).
  3. The user signs in to their NHS Identity account (using a smartcard and PIN, or thumbprint reader, or other method).
  4. Our authorization server redirects control back to the calling application, with an authorisation code.
  5. The calling application calls our OAuth2.0 token endpoint (/oauth/token), with the authorisation code, and receives an access token and an ID token in return.
  6. Time passes, until the user needs to access a user-restricted API.
  7. The calling application calls the user-restricted API, including the access token.
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

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 following diagram illustrates the pattern:

User-restricted RESTful API - security pattern 2

The following sequence diagram shows how the various components interact:

User-restricted RESTful API - separate authentication and authorisation - sequence diagram

In words:

  1. The calling application forwards the user's browser to the NHS Identity authentication endpoint.
  2. The user signs in to their NHS Identity account (using a smartcard and PIN, or thumbprint reader, or other method).
  3. NHS Identity redirects the user's browser back to the calling application, with an auth code.
  4. The calling application calls the NHS Identity token endpoint, with the auth code, and receives an access token and an ID token in return.
  5. Time passes, until the user needs to access a user-restricted API.
  6. The calling application calls our OAuth2.0 token endpoint (/oauth/token), passing the ID token, and receives an access token (a token exchange).
  7. The calling application calls the user-restricted API, including the access token.
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 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: 11 March 2020 9:05 am