/
Integration Guide: Kjernejournal REST API using HelseID as authenticator

Integration Guide: Kjernejournal REST API using HelseID as authenticator

 

Introduction

This is a specification for the technical integration with the different REST APIs that are available from kjernejournal.

Purpose

The purpose is to clarify the premises for the technical organization of the EHR vendor for integration with the API's available from kjernejournal, using HelseID as authenticator. It does not include details on input and output to the various API's, see the page Kjernejournal API-integrasjon for links to the pages with detailed information about the APIs and Swagger documentation.

Target audience

The target audience for this document are technical resources and project management with a responsibility for implementing an integration with kjernejournal.

Limitations

This document is limited to the services and needs that support integration.

This document do not include

  • establishment of operating routines

  • establishment of monitoring routines

  • integration with HelseID to obtain the necessary security tokens for communicating with kjernejournal.

Solution description

The vendor can choose to integrate with several of the kjernejournal APIs. , Norsk helsenett can assist the vendor in assessing which APIs that are relevant for their EHR system and their end-users.

An API-integration with kjernejournal requires:

  • Integration with Health indicator Rest service that indicates whether the patient has kjernejournal or not.

  • Development of dialogs where the information requested from kjernejournal is presented to the end user.

  • Development of dialogs where end user registers the information that is uploaded to kjernejournal (Alert information).

When the user opens a new patient, the EHR system should make an API call to kjernejournal’s health indicator API, which indicates if the patient is registered in kjernejournal, and if any critical information is registered. The EHR system changes the appearance of the kjernejournal icon according to the response from the health indicator API, to signify to the user the level of information that exists in kjernejournal for the patient.

For the different APIs the workflow will vary in the EHR system. The vendor has great freedom to choose the appearance of dialogs that are needed for the integration. Norsk helsenetts requirements are focusing on that the data shall be presented correctly and user-friendly.

 

Workflow using HelseID and API's from kjernejournal

Main functional steps

  1. The client requests and receives a system token from HelseID, which includes the organization number.

  2. The client then sends the signed system token and a patient nin to kjernejournal, which authorizes the organization and creates a ticket that represents both the organization number and the patient.

  3. The client then requests and receives a user token from HelseID. Typically they are authenticated using Buypass or Commfides.

  4. The client then sends both the ticket from kjernejournal, as well as the signed user token to the actual API, which then authorizes the user and responds

  5. The client receives the data from kjernejournal

Note that this is not a required order. The client is free to do step 3 before step 2, or to do step 3 as the user logs onto the client and just store the user token until it is needed.

In these steps, tokens are issued by HelseID, while the ticket is issued by kjernejournal in step 2. Tokens are in jwt format and signed by HelseID, while the ticket is an opaque string only useful for kjernejournal.

 

Authentication of health personell

All API's in kjernejournal require both the ticket described above, but also a user access token (JWT) from HelseId. The EHR must implement HelseID authentication, and must contact HelseID for information. Typically this is done through a web browser, but the EHR is free to do this is any way that is acceptable to HelseID.

The user access token must have the scope nhn:kjernejournal/api. The token must also have the claims https://nhn.no/claims/identity/pid and https://nhn.no/claims/identity/security_level. Only tokens with security level 4 will the accepted.

The token must be attached as a Bearer token i requests to Kjernejournal API's. Typically EHR will use an Authorization code grant with HelseId to get a token. This flow is not described in detail here as it is a Oauth2/OIDC standard.
See  helseid.no and HelseID - NHN Utviklerportal for more information about integrating with HelseID. NB! KJ APIs require access tokens with the API Resource as the only audience, see doc at Requesting multiple access tokens with single audiences

 

Integration description

All requests to kjernejournals API's are done in two steps.

  • First a client token is sent to authenticate the organization, and a ticket is returned.

  • Secondly a user token is sent together with the ticket, which together authenticates both the user and the organization, and gives access to the API. Note that a ticket is valid for one hour, and can be reused for that time. As the ticket contains the patients nin, it will only be valid for the specific patient used in the first step.

Health indicator service

The Health indicator REST service returns the patients status in kjernejournal.

It’s a POST to /v1/helseindikator, with a JSON body (Content-type: application/json) with the following input:

Input:

Field

Location

Required

Description

Field

Location

Required

Description

fnr

Body

Yes

Patient identifier (Norwegian national identity number).

legemiddelFraDato

Body

No

Optional parameter for information about prescriptions.

Example: 2021-06-11

samtykke

Body

No

Consent for opening the patient’s kjernejournal (used if the ticket from the response is later used to access the patient’s kjernejournal).

Can be one of the following values:

  • HPMOTTATTSAMTYKKE

  • HPAKUTT

  • HPUNNTAK

This parameter should be sent for API integrations.

Authorization

HTTP Header

Yes

A token from HelseID sent as a bearer token.

X-EPJ-System

HTTP Header

Yes

Which EHR system, and which version, the request originated from.

 

Output in case of successful request:

Field

Location

Description