Migrating from HSCN/CIS1 to APIM/CIS2

This page explains how to migrate your integrated NHS e-Referral Service (e-RS) application from the Health and Social Care Network (HSCN) to the internet-facing API, accessible via the API Management (APIM) platform.

In particular, it describes deprecation of the e-RS API on HSCN and the Care Identity Service (CIS1) authentication. It also describes authentication and authorisation changes, as well as updates to endpoint URLs.

Partners will be affected if your integrated software uses:

• HSCN
• specific environments
• session endpoints

HSCN

All partners integrated with the FHIR API over the HSCN will be affected. This API can only be used with CIS1.

Environments

You will be affected if your integrated software uses any of the following environments and URLs:

Production - https://api.ebs.ncrs.nhs.uk

Integration - https://api.int1.ers.ncrs.nhs.uk

Deployment - https://api.dep1.ers.ncrs.nhs.uk 

Session endpoints

You will be affected if your integrated software uses the DSTU2 authentication and authorisation endpoints:

A001: Create Professional Session 

A002: Professional Session Select Role 

A003: Delete Professional Session

The e-RS deprecated HSCN access to its API using CIS1 authentication in August 2023. This functionality will be withdrawn from service in August 2024.

At this point, HSCN access and CIS1 authentication will no longer be supported by the e-RS API.

The e-RS internet-facing API, available via APIM, provides enhanced functionality with all the features of the HSCN API.

The e-RS API uses a global standard for health care data exchange - FHIR.

The standard and best integration practices are constantly evolving. The e-RS must adapt and respond to changes. This ensures that the service continues to deliver reliable, secure and cost-effective products.

The Identity and Access Management team have deprecated the Care Identity Service (CIS1). Suppliers must migrate to the Care Identity Service 2 (CIS2) for authentication.

The e-RS HSCN API does not support CIS2. Instead, e-RS offers an internet-facing API via APIM which is compatible with CIS2. These provide enhanced functionality, including application-restricted access and an OpenAPI specification.

Partners using FHIR DSTU2 API endpoints will be required to migrate over to the equivalent FHIR STU3 versions.

The migration guide explains the differences in endpoint changes and base URLs.

The integration process documents the activities required to get your product live.

Partners with existing integrated systems will have carried out much of this work already. However, we advise working through the whole process to understand the differences and to revalidate at each step.

A lighter weight assurance policy will be available for migrations, provided no new functionality is to be adopted.

You must inform us when you start onboarding. You can contact us at [email protected].

The pattern used for authentication with the Internet-facing API is different to that used for the e-RS HSCN API.

The e-RS API delegates responsibility for authentication to APIM and CIS2 directly.

Security and authorisation outlines the security patterns offered by the APIM platform. The "User-restricted: Healthcare Worker access mode" is the equivalent access mode supported by the e-RS HSCN API.

The e-RS supports the User-restricted RESTful API - NHS CIS2 separate authentication and authorisation security pattern.

The security pattern guide details how the pattern works and how it may be used with CIS1 and existing smartcards.

It also describes how to:

• setup your application, including how to register your application with the:
  • NHS CIS2 authentication
  • API platform
• authorise the healthcare worker with NHS CIS2 authentication
• exchange the NHS CIS2 authentication ID token for an access token
• provide the access token when calling a user-restricted e-RS API

It is necessary to provide the selected organisation and business function when calling an e-RS user-restricted endpoint.

The Retrieve user business functions (A030, FHIR R4) endpoint can be used to retrieve the available e-RS business functions at each organisation where the user works.

When calling an e-RS endpoint this organisation and business function is provided using the NHSD-End-User-Organisation-ODS and NHSD-eRS-Business-Function HTTP request headers.

If using the SERVICE_PROVIDER_CLINICIAN_ADMIN business function the NHSD-eRS-On-Behalf-Of-User-ID HTTP request header is used to supply the on-behalf-of SERVICE_PROVIDER_CLINICIAN user ID.

The Retrieve "on-behalf-of" practitioner user information (A040, FHIR R4) endpoint can be used determine which users a SERVICE_PROVIDER_CLINICIAN_ADMIN is allowed to work on-behalf-of.

The endpoint URLs have changed in the following ways - host and base path.

The host is now provided by the APIM platform:

Production: https://api.service.nhs.uk 

Integration: https://int.api.service.nhs.uk 

Deployment: https://dep.api.service.nhs.uk 

The HSCN base path included an endpoint version, for example: /STU3/v1/ReferralRequest/{ubrn}. This is no longer included:

Production: /referrals/FHIR

Integration: /referrals/FHIR

Deployment: /referrals-dep/FHIR

Note that functional endpoint paths will remain unchanged, for example:

Production: Retrieve referral request (A005, FHIR STU3)

/ReferralRequest/{ubrn}

This section provides an example of the differences between using HSCN/CIS1 and the internet-facing API via APIM/CIS2.

It details variances in:

• authentication and authorisation
• calling an e-RS endpoint

This example is calling Retrieve referral request (A005, FHIR STU3) in the integration (INT) environment.