Authorization

In order to be authorized to use the service the client must first be authenticated using HelseID or Helsenorge.

See curl examples of API requests to the service.

HelseID

A HelseID access token is required for authorization of organization and health care personell.

Claims

The client must do a token refresh/exchange with HelseID to set correct audience and scope for this service.

Claim Description
scope List containing "nhn:careplan/api".
aud nhn:careplan
helseid://claims/client/claims/orgnr_parent Org. nr. at the top level (legal entity). Required for all.
helseid://claims/client/claims/orgnr_child Org. nr. at the lower level (point of care). Required for all.

Claims for HelseID can be found here.

Documentation to set single audience can be found here

Headers

Name Description Required
Authorization: Bearer HelseID access token. Yes
hit-user-role Role of the logged in user (see below). Yes
hit-source-system Name and version of the EPJ system, 3-512 characters. Yes
hit-access-basis Basis for access (grunnlag/tjenstlig behov, see below). Yes
hit-patient-pid Patient national identification number (fnr/dnr). Yes
hit-event-id UUID or other id used to trace the request, max 128 characters. No
content-type Required for requests with body (POST/PUT). Yes

hit-user-role

Information about the role of the logged in user. Must be a valid JSON data structure. We require that the content of the header is always URL encoded to make sure all types of characters are transmitted correctly to the server.

Example:

{
    "system": "urn:oid:2.16.578.1.12.4.1.1.9060",
    "code": "LE"
}

The content of the "system" field is the coding system (kodeverk) for the type of role the user got.

System Description
urn:oid:2.16.578.1.12.4.1.1.9060 Volven coding system for HPR role. Used by EPJs.
kjernejournal_userrole Custom coding system for Kjernejournal role. Only used by Kjernejournal.

The content of the "code" field is the role of the user. For HPR all roles must be according to Volven kodeverk 9060. Example HPR roles:

Code Description
LE Lege
SP Sykepleier
PS Psykolog

hit-access-basis

Which basis for access (grunnlag/tjenstlig behov) the user has to get access to data. "Forhøyet" must be used if requesting access to data which the patient has restricted access (sperring).

Note:
If the patient has not set restriction and the "Forhøyet"-values are used in this header, then you will recive an error. Overrule of restriction must only be done when the patient have actually set restriction. See status-endpoint.

Value Use case
UNNTAK Use for persons which has do not have to get consent from the patient, e.g. general practitioner (fastlege). §7 of the Kjernejournal forskriften (regulation) regulates who is exempt from the requirement https://lovdata.no/dokument/SF/forskrift/2013-05-31-563
SAMTYKKE The user has gotten consent from the patient to see data. According to Pasientjournalloven §13 (https://lovdata.no/dokument/NL/lov/2014-06-20-42/KAPITTEL_2#%C2%A713) a Healthcare personnel must be given consent from the patient before retrieving necessary and relevant health information from Kjernejournal when providing healthcare. However, there are some exemptions as described in §7 in kjernejournalforskriften (https://lovdata.no/dokument/SF/forskrift/2013-05-31-563)
FORHOYET_SAMTYKKE The patient has given consent to open restricted data (sperring). The patient can restrict healthcare personnel to look up data from Kjernejournal. However, the health care personnel can retrieve the data if the patient has given their consent. This is only to be set if there are restricted data, and the patient has given their consent to look up the data despite of the restriction. If FORHOYET_SAMTYKKE is set, and there are no restricted data, an error message will be sent.
AKUTT Use when in an emergency situation where the patient is unable to give consent. §7 of the Kjernejournalforskriften (https://lovdata.no/dokument/SF/forskrift/2013-05-31-563) regulates when there is an emergency situation: if there is a serious danger to the patient's life, when there is no time to obtain the patient's consent or if the patient is unable to consent due to their physical or mental condition.
FORHOYET_AKUTT Opens restricted data (sperring) in an emergency situation where the patient is unable to give consent. The patient can restrict healthcare personnel to look up data from Kjernejournal. However, the healthcare personnel can retrieve the data if there is an emergency as described in "AKUTT". This is only to be set if there are restricted data, and an emergency, where the healthcare personnel needs the data despite of the restriction. If FORHOYET_AKUTT is set, and there are no restricted data, an error message will be sent.

hit-source-system

The name and version of the EPJ system, 3-512 characters. If the name contains Norwegian characters then the header content should be URL encoded to make sure all types of characters are transmitted correctly to the server.

Machine to machine

The token must contain the following claims when HelseID machine to machine authorization:

Claim Description
scope List containing "nhn:careplan/api".
aud nhn:careplan
helseid://claims/client/claims/orgnr_parent Org. nr. at the top level (legal entity). Required for all.
helseid://claims/client/claims/orgnr_child Org. nr. at the lower level (point of care). Required for all.

Note that a machine token must not contain the claim "helseid://claims/identity/pid". If so you will get an error.

The headers "hit-patient-pid", "hit-source-system" and "content-type" must also be set (see above).

Machine to machine authorization is used in the /status endpoint.

Helsenorge

For an inhabitant an Helsenorge access token is required.

Read about inhabitant authentication - Helsenorge as OpenID Connect provider here.

Claims

Overview claims for Helsenorge is found here.

Claim Description Required
scp Comma separated list which contains "kritiskinfo". Yes
sub See Helsenorge documentation. Yes
act_sub See Helsenorge documentation. Yes
act_type See Helsenorge documentation. Yes

Headers

Name Description Required
Authorization: Bearer Helsenorge token. Yes
hit-event-id UUID or other id used to trace the request, max 128 characters. No

Error codes authorization

Error codes has prefix "AUTH".

Error code Cause
AUTH-0001 Invalid token signature.
AUTH-0002 Invalid token claim.
AUTH-0003 Invalid http header.
AUTH-0004 Invalid Helsenorge "grunnlag".
AUTH-0005 Internal technical error.
AUTH-0006 Machine to machine token not allowed.
AUTH-0007 Error in Helsepersonellregisteret (HPR).
AUTH-0008 Error when reading public key.
AUTH-0009 Internal communication error.
AUTH-0010 Security related error, e.g. malicious content detected.