Page Status: updated 2022-05-11

HTTP Header and Authorization

Page index

Authorization

Access to the Swedish National Medications List consists of three parts:

  • Required access token in authorization parameter
  • Purpose and access defined in the x-purpose and x-access parameters (required for most read interactions, see required information in each use case)
  • A provenance structure describing information related to who authored and who entered the request as well as why, which relates to the value in the x-povenance request header.

Authorization
Access to the Swedish National Medication List is based on OAuth2 or SAML and requires a valid bearer token. More information is enclosed in the Ansluta till E-hälsomyndighetens tjänster.

Purpose and access type
The information in the purpose and access parameters will, along with the role of the person (in the security token) determine which information will be filtered in the response. This information will be available to the patient in the audit log. See Ändamål, åtkomsttyper, resurser och behörigheter for more information.

Provenance
In most create and update requests, a provenance resource will need to be added as a base64 encoded JSON to the HTTP request header x-provenance. The provenance holds information about who makes the request, the intention of the request and other event related information. Read more about the Provenance resource in the Provenance section.

A complete list of all header parameters can be seen in the table HTTP Headers below

HTTP Request Header

The table below shows HTTP header fields used in a request containing FHIR or NLL specific information. Other fields may be included as well in accordance with the HTTP specification. Mandatory fields are indicated in the column Mandatory

Prefix Comment Example Mandatory
accept Describes formats accepted by client. Only JSON is fully tested by NLL, therefore JSON is the recommended format. Also fhirVersion can be added, but note that NLL currently only supports 4.0 accept: application/fhir+json; fhirVersion=4.0 No. If not present, JSON will be used in response
authorization A security token. Should contain the SAML-token issued by the IdP or the OAuth-token issued by the Swedish eHealth Agency. See Säkerhetslösning Yes, when LOA3 is stipulated
prefer Information to be returned on a successful create or update request See section Managing returned content No
x-access A coded value (see value set access-types) describing the legal ground for the access x-access: TILLFALLIGT_SAMTYCKE Yes, for read operations
x-call-type A request for extended period of validity of the security token. Possible values are NORMAL and DELAYED. See Reservlösning for more information. x-call-type: DELAYED No, default value is NORMAL
x-correlation-id An optional UUID* that is used by the caller to group a sequence of requests. This ID is only used for logging purposes. x-correlation-id: dea7e921-6bac-4098 ... No
x-org-info A BASE64 UTF-8 encoded JSON structure containing information about the organisation of the person requesting information See example below Yes, for applicable operations
x-patientref A reference to the patient by patient ID (UUID*) who's information is requested or updated. This is to ensure that an operation not including a direct patient reference is related to the intended patient x-patientref: dea7e921-6bac-4098 ... Yes, for operations with direct or indirect reference to a specific patient
x-provenance A BASE64 UTF-8 encoded provenance resource. NB! This must be the same provenance as is contained in the body if there is one x-provenance: { "resourceType": "Provenance" ... Yes, for create and update operations
x-purpose A coded value (see value set purpose-types) describing the purpose of the request x-purpose: EXPEDIERING Yes, for read operations
x-proxyref A reference to the person acting as agent for a patient by person ID (UUID*). Only applicable if the purpose is LASA_EGNA_UPPGIFTER x-proxyref: dea7e921-6bac-4098 ... Yes, when an agent is involved
x-request-id An UUID* generated by the caller as a unique ID per request. It is used to ensure that the same request is not performed multiple times. A resend of a request should keep it's request ID. x-request-id: dea7e921-6bac-4098 ... Yes
x-user-agent A BASE64 UTF-8 encoded JSON structure containing information about the calling system See example below Yes

*UUIDs generated by the Swedish National Medication List follows RFC 4122 type 4, with a few exceptions when type 3 is used, and the FHIR 4 specification. RFC 4122 allows UUIDs to be in both upper and lower case but FHIR states that UUID IDs shall be in lower case. UUIDs in the Swedish National Medication List are therefor allways in lower case and alla UUIDs sent to the Medication List should be in lower case.

Examples

x-org-info

x-org-info is part of the security mechanism and is used to provide security information that is not included in the security token.

Health care providers use SAMBI and are therefore required to provide the city name.

{
    "orgenhetsOrt" : "Kalmar"
}

Web pharmacy services use the patient's security certificate, or a related person's security certificate, and must therefore provide the web pharmacy's GLN number.

{
    "orgenhetsId" : "7350045511996",
    "orgenhetsIdTyp" : "GLN",
}

x-user-agent

{
  "name" : "Pascal",          // mandatory and max 20 characters
  "info" : "Module Z1",       // optional and max 99 characters
  "version" : "4.3.1",        // mandatory and max 20 characters
  "moduleVersion" : "1.0.2"   // optional and max 19 characters
}

  • name should contain the product name of the user agent making the call.
  • info may contain additional information about the user agent for example a module name or name of a customer specific extension.
  • version should contain the version number of the user agent. Preferable a technical version string rather than a marketing version name.
  • moduleVersion may contain an additional version number indicating the version of a module or extension.

HTTP Response Header

The table below shows HTTP header fields used in a response containing FHIR or NLL specific information. Other fields may be included as well in accordance with the HTTP specification.

Prefix Comment Example
content-location content-location: [base]/MedicationRequest/0f1d0ca9-b035-43c7 ...
location location: [base]/MedicationRequest/0f1d0ca9-b035-43c7 ...
x-request-id The x-request-id provided in the request is returned in the response x-request-id: 475c583d-4873-4beb ...