Make the FHIR call
With an access token, you can query the other care organization's FHIR API (or other data API).
The token is either a DPoP token (the default) or a Bearer token, depending on token_type in your token request. DPoP is optional, but more secure: every request also needs a DPoP header, which proves the request comes from you, the party the token was issued to. A stolen DPoP token is useless without your node's key. Your Nuts node creates the DPoP header for you.
Before you start
- You have an access token and its
dpop_kid(see "Request an access token"). - You have the other care organization's API endpoint, from its
registrationParameters(see "Find care organizations and their endpoints"). - Your client can connect to the other party's API. Data endpoints are protected with mTLS (see "Endpoints and TLS certificates").
1. Create the DPoP header (DPoP tokens only)
Create a new DPoP header for every request. It's only valid for one HTTP method and URL, and can only be used once.
POST <internal Nuts interface>/internal/auth/v2/dpop/<dpop_kid, URL-encoded>
Content-Type: application/json
{
"htm": "<HTTP method>",
"htu": "<URL of the request>",
"token": "<access token>"
}
| Field | Value |
|---|---|
<dpop_kid> (in the URL) |
dpop_kid from the token response, URL-encoded once, e.g. # becomes %23 |
htm |
The HTTP method of the request you're about to make, e.g. GET |
htu |
The URL of the request you're about to make. Query parameters are ignored. |
token |
The access token |
The response:
{
"dpop": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0In0..."
}
2. Make the request
Send the access token in the Authorization header with the type DPoP, and the DPoP header in DPoP:
<HTTP method> <URL of the request>
Authorization: DPoP <access token>
DPoP: <dpop from step 1>
For a Bearer token, skip step 1 and send Authorization: Bearer <access token>.
Errors
| Response from the other party | What to do |
|---|---|
401 Unauthorized |
The token expired, or the DPoP header doesn't match the request. Check htm and htu. If the token expired, request a new one. If it hasn't expired, the other party may have lost it: request a new token with the header Cache-Control: no-cache, which skips your node's token cache. |
403 Forbidden |
The other party doesn't allow this query, e.g. no legal basis such as consent. Check the use case's rules. |
360-graden-clientbeeld
Use fhirR4BaseURL or fhirStu3BaseURL from the search result, depending on which FHIR version the other party offers. The examples below use R4, with base URL https://fhir.other.example/r4.
1. Get the CapabilityStatement. It says which queries the other party supports. It doesn't need an access token, and you need it before any query other than Patient.
GET https://fhir.other.example/r4/metadata
2. Find the patient by BSN. Only POST-based search is allowed. Create the DPoP header with htm POST and htu https://fhir.other.example/r4/Patient/_search.
POST https://fhir.other.example/r4/Patient/_search
Content-Type: application/x-www-form-urlencoded
Authorization: DPoP <access token>
DPoP: <dpop>
identifier=http://fhir.nl/fhir/NamingSystem/bsn|123456789
The result has the patient's ID at the other party, e.g. Patient/abc123.
3. Query the data. For example, the patient's allergies. Create a new DPoP header with htm GET and htu https://fhir.other.example/r4/AllergyIntolerance.
GET https://fhir.other.example/r4/AllergyIntolerance?patient=abc123&_profile=http://nictiz.nl/fhir/StructureDefinition/nl-core-AllergyIntolerance,http://nictiz.nl/fhir/StructureDefinition/zib-AllergyIntolerance
Authorization: DPoP <access token>
DPoP: <dpop>
- Queries select resources by FHIR profile (
_profile). Volume 3 of the IG lists the query for each zib and FHIR version. - Results are paged: use
_count(maximum 100) and follow the bundle'snextlink. - The order of requests is in volume 2b of the IG.
API reference: Auth (v2)