Skip to main content

Onboarding (koppelen)

Before the DPVA-r can be accessed by the HAPIS the HAPIS should complete an onboarding procedure. This procedure is explained in this document.

The onboarding procedure consists of 4 steps.

  1. The HAPIS sets up a connection to the DVPA-r using HTTP over mutual TLS (mTLS)
  2. The DVPA-r validates the connection request
  3. The DVPA-r sends a one-time authorization token to the HAPIS using an out-of-bound transport
  4. The HAPIS sends the authorization token over the original mTLS connection.
info

The DVPA-r API the onboarding API have their own versioning. The version is represented in the service's base URL. Currently the version is v1. If (breaking) changes occur in the onboarding API its version and URL will change accordingly.

1. Request a connection​

When the HAPIS wants to request a connection it sends a HTTP POST request to the /onboarding/v1/connection endpoint with a JSON payload containing the following information.

  • organizationFormalName (string)
    Formal (KvK) name of the organization that controls the HAPIS
  • organizationIdentifier (string)
    Identifier for the organization (HAP), e.g., UZI (URA) identifier, or KvK
  • organizationIdentifierType (string)
    Type of identifier used as organizationIdentifier, e.g., AGB or KVK number. (examples)

As a result a connectionRequestIdentifier is returned. This identifier is unique for this connection request. This connectionRequestIdentifier is necessary to complete this connection in a later call so it should be saved somewhere for later usage.

info

This request should be done over a mTLS connection, that is, using a client certificate. The public key of this client certificate is bound to the connection request and to the connection that is the result of this onboarding procedure. In other words, subsequent calls to the DVPA-r API can only be made using a client certificate with the same public key.

Example

If a client wants to request a connection with the DVPA-r it sends to following request to the DVPA-r's /onboarding/v1/connection endpoint

POST /onboarding/v1/connection
Content-Type: application/json
... 

{
    "organisationFormalName": "Huisartsenpost Binnenveldertse Gouw",
    "organisationIdentifier": "67891234",
    "organisationIdentifierType": "KvK"
}

As a result the DVPA-r returns the following response

200 OK
Content-Type: application/json
...

{
    "connectionRequestIdentifier": "1234-abcd"
}

2. Validate the connection request​

The intent of this request is that the owner of the DVPA-r can validate if the request is legitimate. This can be done by looking up the requesting organisation in the KvK register and / or the AGB register. The next step is to seek contact with the organisation using the contact information (e.g., postal address) obtained from these official registers and establish that the request is actually initiated by this organisation.

If so, the connection request is marked valid and a connectionRequestToken is created and associated with this connection request. This connectionRequestToken, in combination with the unique connectionRequestIdentifier, must be used by the HAPIS to complete the connection.

3. Send connectionRequestToken to the HAPIS by means of an out-of-bound transport​

Next the owner of the DVPA-r should send this connectionRequestToken to the owner of the HAPIS by means of an out-of-bound transport, for example via mail or via telephone.

4. Send the acquired connectionRequestToken to the DVPA-r to complete the connection​

info

This request should be done over a mTLS connection using the same client certificate as used in the connection request (step #1).

Once the owner of the HAPIS has received the connectionRequestToken it can be used to complete to connection request by sending a HTTP POST request to the /onboarding/v1/connection/{connectionRequestIdentifier} endpoint.

Here the connectionRequestIdentifier that is acquired in step #1 is required. The connectionRequestToken is bound to this specific connection request. So if the connectionRequestIdentifier acquired in step #1 is 1234-abcd and the connectionRequestToken is 5678-efgh the following request should be made to complete the connection:

POST /onboarding/v1/connection/1234-abcd
Content-Type: application/json
...

{
  "connectionRequestToken": "5678-efgh"
}

If the request validates -- the connectionRequestToken is actually the one that is bound to this connection request -- the connection is completed by the DVPA-r and the other DVPA-r API methods can be invoked by the HAPIS using the same client certificate used for setting up this connection.