# Access to Koppeltaal ## Request Flow {% hint style="info" %} For an interactive demo, go to our [Koppeltaal Test Tooling](https://testsuite.koppeltaal.headease.nl/). {% endhint %} Koppeltaal requires that applications use the [SMART Backend Services: Authorization](https://hl7.org/fhir/uv/bulkdata/authorization/index.html#obtaining-an-access-token) flow to request an `access_token`. The following diagram is used for this purpose ![SMART Backend auth flow](/files/IN5x8t7jO2nkyzlOOHl6) {% hint style="info" %} The contents of the JWT and the OAuth request are described in detail [here](https://hl7.org/fhir/uv/bulkdata/authorization/index.html#protocol-details). Koppeltaal has an exception to the `scope` parameter. It may be sent by the client, but its value is set by the auth server based on the client's role. {% endhint %} {% hint style="warning" %} The FHIR documentation mentions multiple `alg` header values (e.g., RS384, ES384). Within the POC environment, we only support RS512. {% endhint %} ### 1. JWT creation The above diagram shows that a JWT token is first compiled and [signed](/technische-howto/connectie-maken-met-koppeltaal/requirements/jwt-ondertekenen.md). The following fields must be set: | Field | Value | | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | iss | Fill with the `client_id` value provided while [Joining a domain](/domain-access/domein-toetreden.md) | | sub | Fill with the `client_id` value provided while [Joining a domain](/domain-access/domein-toetreden.md) | | exp | UNIX timestamp of now + 5 minutes | | aud |

Fill with

(value can be extracted from the SMART on FHIR conformance)

| | jti | Random identifier, this is used by the auth server to prevent replay attacks. Use something like a GUID here. | ### 2. Access Token Request Execute the following request: ## Request access\_token `POST` `https://auth-service.koppeltaal.headease.nl/oauth2/token` See the Response tab for an example response. #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ----------------------------------- | | Content-Type\* | string | `application/x-www-form-urlencoded` | #### Request Body | Name | Type | Description | | --------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------- | | client\_assertion\* | string | The signed JWT | | client\_assertion\_type\* | string |

Always fill with

urn:ietf:params:oauth:client-assertion-type:jwt-bearer

| | grant\_type\* | string |

Always fill with

client\_credentials

| | scope\* | string |

Content can be empty. The

scope

is set by the auth server based on the client's role

| {% tabs %} {% tab title="200" %} ```javascript { "access_token": "eyJraWQiOiJKR3pTYmgzVS1TQlVabllIQjJQaWhzN0FBc0Vubk8zelpqUS1RSjFTN0tzIiwiYWxnIjoiUlM1MTIiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2F1dGhlbnRpY2F0aW9uLXNlcnZpY2Uua29wcGVsdGFhbC5oZWFkZWFzZS5ubC8iLCJhdWQiOiJmaGlyLXNlcnZlciIsIm5iZiI6MTYzMTE5NDM0MCwiZXhwIjoxNjMxMTk3OTQwLCJub25jZSI6IjQ4NTI5NTc2LTFiZTctNGNmOS04MWM0LWRkMTVhMjE4NjcwNyIsInR5cGUiOiJhY2Nlc3MiLCJzY29wZSI6IiIsImF6cCI6IjVhZDdjZjZhLTk1NTYtNGQyMy05MWNhLTI1MGRhZmExZGYwOSJ9.cgBzTRhbvLFPug9bqvCtaVi9ogHpMDqqemoTJjA1C3OpMsU42VyrnNUZ41qtcsZfqjI5OspT678MyVhDHq6DDRc9GLbg8RFLjrow17PfBCgkFALCKXWi9r6gTOZdaGdEPKfqavn1r8-S2HnIaWdEVfNPA1ZlBBxkJsYLl-8zgPmykZDNCbIH1e_SevGc56GeF5dPjHzxSiAI2_t19FM0OL3JfLZ-T8DR5tcOo7xfDYD086AUUr0hQIkzbrhuLGHSM5X6QcX84IfZlC0jQ6v_YbdMXlMBDZfUZN1nbsjxtDRwiz0IzZtIOF1XXpS1j0rKy517Vu_cc6LOS1OasUAAEw", "expires_in": 3600, "token_type": "Bearer" } ``` {% endtab %} {% tab title="400" %} The request has been submitted incorrectly. Probably due to missing parameters or the body is delivered in the wrong way. {% endtab %} {% endtabs %} As shown above in the 200 Response, the `access_token` is passed as part of the response. This `access_token` must be passed along as a `Bearer` token in the [`Authorization` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) on every request to the Koppeltaal server. The format of the header is as follows: ``` Authorization: ``` In the example response, the header should look like this: ``` Authorization: Bearer T8DR5tcOo7xfDYD086AUUr0hQIkzbrhuLGHSM5X6QcX84IfZlC0jQ6v_YbdMXlMBDZfUZN1nbsjxtDRwiz0IzZtIOF1XXpS1j0rKy517Vu_cc6LOS1OasUAAEw ``` ### Refreshing the access\_token The `access_token` has a relatively short lifetime. When the token expires, the Koppeltaal server will return a `401` error. The [SMART Backend Services: Authorization](https://hl7.org/fhir/uv/bulkdata/authorization/index.html#obtaining-an-access-token) does not support a `refresh_token`. The application needs to redo steps 1 & 2. ## Topics [TOP-KT-005c - Applicatie toegang: SMART on FHIR backend services](https://vzvz.atlassian.net/wiki/spaces/KTSA/pages/27125356/TOP-KT-005c+-+Applicatie+toegang+SMART+on+FHIR+backend+services) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://devguide.koppeltaal.nl/technische-howto/connectie-maken-met-koppeltaal/toegang-tot-koppeltaal.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.