Authorization
In order to be authorized to use the service the client must first be authenticated using HelseID or Helsenorge.
HelseID
A DPoP token from HelseID is required for authorization of organization and health care personell.
Authorization using HelseID Bearer token will be phased out in the future. We encourage all clients to migrate to DPoP as quickly as possible.
Note that the EPJ system must provide the org. nr. of the actual work place (point of care) of the health care personell when requesting the access token. This will make sure that the request is connected to the correct organization.
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:critical-information/api". |
| aud | nhn:critical-information |
| 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 documentation for HelseID can be found here.
Documentation to set single audience can be found here
Headers
| Name | Description | Required |
|---|---|---|
| Authorization: DPoP |
HelseID DPoP access token. | Yes |
| DPoP | DPoP proof. | 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). Must be a valid nin from folkeregisteret/persontjenesten | Yes |
| hit-event-id | UUID or other unique 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. Note that for HPR roles it must be active in HPR, or else the request will be rejected.
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 | Description |
|---|---|---|
| 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. |
| SAMTYKKE | The user has gotten consent from the patient to see data. | According to Pasientjournalloven §13 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. |
| 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 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 token
A HelseID machine to machine token is a regular HelseID access token, but it does not contain the user pid claim or any other user data.
The main use case is to request certain endpoints without requiring the user to log into the EPJ or HelseID first. Whether to use it or not is up to the EPJ based on how the API is used.
The token must contain the following claims when HelseID machine to machine authorization:
| Claim | Description |
|---|---|
| scope | List containing "nhn:critical-information/api". |
| aud | nhn:critical-information |
| 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 to machine token must not contain the claim "helseid://claims/identity/pid". If so you will get an error.
Only the headers "hit-patient-pid" and "hit-source-system" are required for machine to machine tokens. The "content-type" header must also be set depending on the HTTP method used (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" or "innsynregisterinnhold". | 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 unique id used to trace the request, max 128 characters. | No |
Error codes authorization
We're sending all error codes related to authorization in the response header nhn-error-code. These error codes has prefix "AUTH".
In order to support Kjernejournal backwards compatibility we've kept some of the old error codes (prefix KJF).
We're also sending all error codes in the response header X-KJ-Feilkode to keep backwards compatibility.
Other Kjernejournal error codes which are not listed below are no longer in use.
Note that both the old Kjernejournal error codes and response header will be phased out in the future.
| Error code | Error code KJ legacy | Cause |
|---|---|---|
| AUTH-0001 | AUTH-0001 | Invalid token signature. |
| AUTH-0002 | AUTH-0002 | Invalid token claim. |
| AUTH-0003 | AUTH-0003 | Invalid http header. |
| AUTH-0004 | AUTH-0004 | Invalid Helsenorge "grunnlag". |
| AUTH-0005 | AUTH-0005 | Internal technical error. |
| AUTH-0007 | AUTH-0007 | Error in Helsepersonellregisteret (HPR). |
| AUTH-0008 | AUTH-0008 | Error when reading public key. |
| AUTH-0009 | AUTH-0009 | Internal communication error. |
| AUTH-0010 | AUTH-0010 | Security related error, e.g. malicious content detected. |
| AUTH-0011 | AUTH-0011 | DPoP proof error. |
| AUTH-0012 | KJF-000132 | The user does not have a valid HPR authorization. |
| AUTH-0013 | KJF-000216 | Token has incorrect security level. |
Kjernejournal legacy authorization
In order to support backwards compatibility for EPJs using Kjernejournal legacy authorization we allow the old Kjernejournal headers and access token to be used.
New consumers of the API are not to use this legacy authorization, and excisting consumers will be asked to switch to the ordinary authorization.
Hence, the legacy authorization will not be supported in the future.
Ticket and HelseID token
EPJs can use Ticket from Kjernejournal's Health Indicator service together with an HelseID access token for authorization.
Header values can be found here.
Scope for the HelseID access token must be "nhn:kjernejournal/api" and audience must be "nhn:kjernejournal".
Helsenorge token
For an inhabitant an Helsenorge access token can be used.
Header values are the following.
| Name | Description | Required |
|---|---|---|
| x-access-token | Helsenorge access token. | Yes |
| x-fnr | National identification number for subject (fnr/dnr). | Yes |