Stage 1.4 - Select your authentication level

When accessing e-RS data via the API there are a few options which must be considered.

NHS England hosts a centralised platform for APIs, providing:

• a front door for healthcare APIs in the NHS
• a single place for consumers to interface with APIs
• a wealth of management controls

All APIs provided via APIM are surfaced over the internet. In some cases, a HSCN connection may be required for the needs of authentication. For example, where the end-user organisation already has a high usage of smartcards.

To access the API platform, you will need a developer account.

By signing up, you will unlock access to a host of APIs, not just e-RS.

Authentication is provided by the API platform and they have documented their access patterns.

e-RS only permits the use of access modes:

• Application-restricted (unattended)
• User-restricted

Application-restricted means verifying the calling application. There isn't an expectation of a user being present, this may be beneficial for some offline/batch processes.

Of the identified security patterns, e-RS will only permit the use of signed JWT authentication.

Without a user being present, there is a limit to the endpoints which can be called. This is due to a number of factors such as:

• the business logic within e-RS constantly checks the Legitimate Relationship (LR) between the user and the patient - this ensures the user has a valid reason to view a patient's referral record as they are involved in their care
• the service adheres to the Care Record Guarantee, ensuring we have a full audit of who has accessed and updated a record

As such, only read-only endpoints are currently permitted in an application-restricted pattern.

Application-restricted endpoints can be identified in the endpoint overview.

1.11 Application-restricted governance 

When working on behalf of many NHS organisations, partners will need a clear separation of data. This is to ensure adherence to NHS England's cyber security requirements.

Currently, partners must provide a separate application per NHS organisation. We acknowledged this could be a burdensome process and work is in the pipeline to amend this position.

There is also a need to appoint a senior responsible owner to own this access route.

Access via this pattern will be restricted to a named user.

An end user must be:

• present, authenticated and authorised
• a healthcare worker
• strongly authenticated and authorised by NHS CIS2 Authentication 

To use this access mode, use one of the following security patterns:

• user-restricted RESTful API - using NHS CIS2 - separate authentication and authorisation
• user-restricted RESTful API - using NHS CIS2 - combined authentication and authorisation

Authentication via Care Identity Service authentication (aka ‘CIS1’) is not permitted for use with the e-RS FHIR API through APIM. End-users can continue to use existing smartcards as these are supported by CIS2, as are other authenticator patterns.

Please contact [email protected] to discuss any identity and access management needs in further detail.

Although you may not directly interact with these artefacts, this section attempts to provide some context for your integration:

• Accredited System Identifiers (ASID)
• Message sets
• Legitimate relationships (LR)

An ASID is an identifier used in Spine Directory Service (SDS) to reference an IT system which has been accredited for use in a specific health or care organisation.

Your application created within the APIM platform will be bound to an ASID - this is a one-to-one mapping.

2.11 Multiple ASIDs

You will need multiple ASIDs if you're working with many end user organisations (EUO) and using both access modes.

If your integrated software uses:

• both access modes, you will need an ASID for each access mode
• the application-restricted access mode for both referrer and provider capability, you will need an ASID for each capability

For example, your integrated software includes: user-restricted, application-restricted (referrer) and application-restricted (provider) access modes.

Your setup would require 3 ASIDs per EUO:

1. [Organisation Name] - [Product Name] – Prod - User-Restricted (ASID 1)

2. [Organisation Name] - [Product Name] – Prod - Application-Restricted - Referrer (ASID 2)

3. [Organisation Name] - [Product Name] – Prod - Application-Restricted - Provider (ASID 3)

2.12 Sharing with other NHS services

The e-RS ASID model also restricts which NHS services the ASID can be shared with.

For those NHS services on the APIM platform, the ASID cannot be shared. For example: PDS (Personal Demographics Service), EPS (Electronic Prescription Service) or SCR (Summary Care Record). You will require a separate ASID for these collective services.

Other NHS services can be shared. Such as: NEMS (National Events Management Service), CP-IS (Child Protection - Information Sharing service) or GP Connect.

Each ASID is associated with one or many message sets.

A message set is a group of interactions, which in this case would be an API endpoint. This allows e-RS to permit or restrict which API endpoints each partner can call at a granular level. This doesn't however restrict what data can be accessed, this is controlled separately by the user permissions associated with the authentication event via CIS2.

Legitimate relationships (LR) enables an electronic relationship with a patient, in the context of their care.

The relationship can be between a patient and a healthcare professional, an NHS organisation, or another person.

The e-Referral Service ensures that only those users with a legitimate need to see a patient's referral information can do so. If the user doesn't work at the organisation or has the incorrect role at that organisation then access to the data is not permitted.

The LR is based on the information provided at the point of authentication. A subsequent check for authorisation is made by e-RS.

The authorisation check can take a few forms:

1. The user only has one role at one organisation and the interaction can proceed without issue.

2. The user has many roles at many organisations. For example, a locum GP or consultant. Use the Retrieve e-RS business functions endpoint to find the most suitable role.

3. The user does not have the correct role for clinical access. In this case, the user can switch roles to another user who has the desired access. We call this working 'on behalf of'. For example, an administrator working on behalf of a clinician. Use the Retrieve e-RS specific practitioner information endpoint to determine an on behalf of role.

Partners must use a client/server integration.

It is not appropriate to call the e-RS platform directly from a client's browser.

All our integration options require a public/private key pair to be used in some form. For this reason, it would not be appropriate to distribute private keys to clients' PCs. The API Management platform requires a fixed call-back URL for both your public key and also to support the OIDC Token Exchange process.

We don't support direct browser based access to our API.

Get support on integrating with our API by checking out our developer community.

You can:

• search and find answers to your query
• post your own questions
• join a community of professionals with similar objectives