HelseID Authorization

In order to be authorized to use the Pasientens Prøvesvar API, the client must first be authenticated using HelseID. For more information on how to register a client with HelseID, see Selvbetjening.

Either A DPoP token or a Bearer token from HelseID is required for authorization of organization and health care personnel.

⚠️ Phasing out Bearer token. Authorization using HelseID Bearer token is being phased out, and is not available on API v2 routes, where a HelseId DPoP token is required. We encourage all clients to migrate to DPoP as quickly as possible. See HelseID's documentation on DPoP tokens.

Be sure to keep up to date with the upcoming changes to HelseID, such as updated requirements for pushed authorization request (PAR) and demonstrating proof of posession (DPoP).

Claims

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

Claim Description Comment
scope nhn:pps/provesvar-read API v1 requires a different scope. See the scope section.
aud nhn:pps API v1 optionally accepts nhn:nilar (OBSOLETE) as an alternative.
helseid://claims/identity/pid National identity number (birth number) of the requester
helseid://claims/hpr/hpr_number Health personnel number according to NHN’s coding standard
helseid://claims/identity/security_level What level of security is used. Must be 4 or higher
helseid://claims/client/claims/orgnr_parent Org. no. at the top level. Legal entity
helseid://claims/client/claims/orgnr_child Org. no. at the lower level. Point of care

Claims documentation for HelseID can be found here.

Read more about the concepts in the Selvbetjening docs.

Scope

The scope depends on what base URL (API v1 or API v2) is being used when accessing out API.

  • API v2: Use scope nhn:pps/provesvar-read. The other scopes are not supported by this base URL.
  • API v1: Use scope nhn:pps/provesvar or nhn:nilar/api (OBSOLETE).

Headers

Name Value/Description Required
Authorization - DPoP <helseid-dpop-token> for DPoP (recommended)
- Bearer <helseid-access-token> for Bearer (phasing out)		 Yes
DPoP HelseID DPoP proof. Yes *
person-id Patient's national identification number (fnr/dnr). Yes
correlation-id ** Correlation ID. Required for requests with body (POST/PUT). Yes
access-basis Legal basis for requesting access (grunnlag/tjenstlig behov, see section access-basis). No ***
requester-hpr-role Requester's HPR role, e.g. "LE" (Lege), "AA" (Ambulansearbeider), see section requester-hpr-role. No
grunnlag (OBSOLETE) Replaced by access-basis. No

* The DPoP header is optional if using Bearer authentication.
** correlation-id is only one of multiple supported correlation ID headers.
*** access-basis will be required for health professionals in the future. Disallowed if the requester is verifikasjonspersonell or saksbehandler.

correlation-id (& Equivalent Headers)

Here is a list of supported correlation ID headers (not case sensitive):

  • Cid
  • Traceparent
  • Correlation-Id
  • Correlationid
  • Correlation
  • X-Correlation-Id
  • X-Correlationid
  • X-Correlation
  • X-Request-Id
  • X-Requestid
  • X-Request

access-basis

On which legal basis (grunnlag/tjenstlig behov) the user requests access to data. Only to be used by requesting health professionals. FORHOYET_... must be used if requesting access to data the patient has restricted access (sperring) to.

FORHOYET_SAMTYKKE and FORHOYET_AKUTT should only be used to access existing data that is not accessible with other access-basis values. Using either when no additional data would be returned, will cause the request to fail.

Value Use case
UNNTAK Used by health professionals who do not require consent from the patient, e.g. general practitioner (fastlege).
SAMTYKKE The health professional has received consent from the patient to see their data.
FORHOYET_SAMTYKKE The patient has given consent for the health professional to see restricted data (sperring).
AKUTT Used when in an emergency situation where the patient is unable to give consent.
FORHOYET_AKUTT Gives access to restricted data (sperring) in an emergency situation where the patient is unable to give consent.

requester-hpr-role

The role of the requesting health professional. This header is going to be required moving forward, but is currently not required. A list of possible roles can be found when searching for code 9060 on FinnKode.

Note that allowed roles might be only a subset of the complete list of roles in the future.

The header should be set to the shortform code, e.g. requester-hpr-role: SP.

grunnlag (Obsolete)

⚠️ Obsolete - Use access-basis instead.

  • default - 0
  • samtykke - 1 (overrides access restriction of type sperring)
  • akutt - 2 (overrides access restriction of type sperring)