The usage of organization numbers

If a client software needs to consume an API that wants organization numbers in the Access token, either as a parent unit, or as a child unit, the software must send a JSON structure (described below) to HelseID. This structure will then contain one or two organization numbers.

ℹ️  An exception for single-tenant clients

The exception for this case is single-tenant clients that needs to consume one or more APIs which only need organization numbers for the parent unit. In this case, the organization number for the parent unit will be automatically set in the Access token, without the need for the software to send in a JSON structure to HelseID. However, if the API also needs organization numbers for any child unit, the software needs to send in a JSON structure as described below.

Patterns for transfering organization numbers

Various patters for sending in a JSON structure with organization numbers to HelseID can be used.

Having a logged-in user

If your client software, or an API it needs to consume, needs a logged-in user, you can employ two patterns in order to transfer organization numbers to HelseID:

  1. Either do a request to the PAR endpoint, by passing in the JSON structure in a Request object/Authorization Details

  2. Or do a request to the Token endpoint, by passing in the JSON structure in the client assertion

Machine to Machine (M2M)

If a logged-in user is not required, you can use the Machine to Machine flow (Client Credentials). In this case, the client software must create a request to the Token endpoint, where the value for grant_type is client_credentials, and the JSON structure is located in the client assertion.

The structure for including organization numbers in requests to HelseID

Disregarding what kind of pattern you use for the transfer of organization numbers to HelseID, you must use a JSON structure for this purpose. This structure will have a different content, dependent on whether the client software that transfers the organization number information is either single-tenant or multi-tenant.

The structure for including organization numbers for single-tenant clients

Single-tenant clients do not include the organization number for any parent unit: this information is already in HelseID's database.

The following structure must be used for transmitting an organization number for a child unit:

{
    "type":"helseid_authorization",
    "practitioner_role": {
        "organization": {
            "identifier": {
                "system":"urn:oid:2.16.578.1.12.4.1.4.101",
                "type":"ENH",
                "value":"974589605",
            }
        }
    }
}

Notice that only the organization number for the child unit (974589605) is transmitted in this structure. Also not that the system value needs to have the value urn:oid:2.16.578.1.12.4.1.4.101.

The structure for including organization numbers for multi-tenant clients

Multi-tenant clients include the organization number for a parent unit, and may also include the organization number for a child unit.

The following structure must be used for transmitting a organization numbers for a parent unit, and possibly, a child unit:

{
    "type":"helseid_authorization",
    "practitioner_role": {
        "organization": {
            "identifier": {
                "system":"urn:oid:1.0.6523",
                "type":"ENH",
                "value":"NO:ORGNR:972418013:974042436",
            }
        }
    }
}

In this case, organization numbers for both the parent unit (972418013), and for the child unit (974042436?) are set in this structure. Also not that the system value needs to have the value urn:oid:1.0.6523.

If the clients only want to send the organization number for a parent unit, the parameter value must be set as this:

"value":"NO:ORGNR:972418013",

An example of a complete structure

This example shows a structure for organization numbers that use the authorization_details claim, set in a Request Object in a request to the Par endpoint:

{
  "alg": "RS256",
  "kid": "B2C61A07EE0661237D19BEE1E0A1463C",
  "typ": "JWT"
}.{
  "authorization_details":
  [{
    "type":"helseid_authorization",
    "practitioner_role": {
      "organization": {
        "identifier": {
          "system":"urn:oid:1.0.6523",
          "type":"ENH",
          "value":"NO:ORGNR:972418013:974042436",
          }
       }
      }
  }],
  "sub": "f7cd1256-0526-4b5a-b4c3-f054c984ace8",
  "iat": "1716644273",
  "jti": "cf6a320674cf44cba9177ac6f84103a3",
  "nbf": 1716644273,
  "exp": 1716644333,
  "iss": "f7cd1256-0526-4b5a-b4c3-f054c984ace8",
  "aud": "https://helseid-sts.test.nhn.no"
}.[Signature]

Use of the Token endpoint

As described above, HelseID will support that a client includes information about organization numbers both in requests to the Par endpoint, as well as to the Token endpoint. The information content is structured in the same way in both cases, but by using the Token endpoint, you must use the claim assertion_details instead of authorization_details.

In this case, the client assertion will contain the following claim:

{
  ...
  "assertion_details": [{
     ... innhold som ovenfor ...
   }]
}