Environments and PKIoverheid certificates
For product owners and partners: Use this page to understand which MediKIT API environments exist and where a PKIoverheid (PKIO) client certificate is required. Certificate procurement takes time, so arrange it before you plan an acceptance or production integration.
For architects and developers: Use this page to pick the host for your target environment, and to understand how the client certificate and the OAuth 2.0 access token each contribute to access.
The MediKIT API is delivered through separate, isolated environments. Each environment has its own hosts, credentials, and organization data. Credentials issued for one environment never work on another.
Environments
| Environment | Host | Client certificate | Purpose |
|---|---|---|---|
| Development (insecure) | https://dev-api-insecure.medikit.nl | Not required | A first look at real API responses without a certificate. Best effort: availability and data are not guaranteed. |
| Development | https://dev-api.medikit.nl | PKIO required | The same environment over mutual TLS. Best effort: availability and data are not guaranteed. |
| Acceptance | https://acc-api.medikit.nl | PKIO required | Verify your integration in a production-like setting before go-live. |
| Production | https://api.medikit.nl | PKIO required | Live patient data. |
You receive the token endpoints, client credentials, and organization IDs for your environments from Nedap MediKIT during onboarding.
Where to build and where to verify
Build and iterate against your own mock of the MediKIT API. The development environment is not intended for partner development: its stability is not guaranteed, and it can change or be unavailable without notice. Use the insecure development host for a first look at real responses, and verify your integration on acceptance.
What PKIoverheid (PKIO) is
PKIoverheid is the Dutch government public key infrastructure. A PKIO certificate is an X.509 client certificate issued under the PKIoverheid trust hierarchy that identifies your organization to Dutch government and healthcare services.
For the MediKIT API, a PKIO client certificate is used to establish mutual TLS (mTLS) on the acceptance and production environments.
Certificate and token requirements
A valid PKIO client certificate establishes the TLS connection. Everything after that is token based: MediKIT authorization is enforced using OAuth 2.0 access tokens and organization scope.
For acceptance and production, both are required:
- A valid PKIO client certificate for the TLS connection.
- A valid OAuth 2.0 access token with access to the requested
organizationId.
You do not need to pre-register your certificate with Nedap MediKIT, and replacing it needs no coordination with us as long as the replacement is a valid PKIoverheid certificate.
Sending the certificate chain
Your client must present the full certificate chain during the TLS handshake, not only your own
(leaf) certificate. Many HTTP clients and libraries send only the leaf by default. The gateway then
cannot link your certificate to a trusted PKIoverheid root, and the request fails with
400 The SSL certificate error. A request without any client certificate fails with
400 No required SSL certificate was sent.
Send, in this order:
- Your own client certificate (the leaf).
- The issuing CA of your certificate service provider, for example
KPN PKIoverheid Private Services CA - G1. - The PKIoverheid domain CA,
Staat der Nederlanden Private Services CA - G1.
Do not send the root (Staat der Nederlanden Private Root CA - G1): the gateway already has it.
The issuing CA depends on the certificate service provider that issued your certificate. All PKIoverheid CA certificates can be downloaded from cert.pkioverheid.nl.
To check what your client sends, run:
openssl s_client -connect acc-api.medikit.nl:443 -cert client.pem -key client.key -cert_chain chain.pem
The Certificate chain section of the output should list your certificate and both intermediates.
What you need to arrange before acceptance and production
- Obtain a valid PKIoverheid client certificate for your organization from a PKIoverheid-recognised certificate service provider. Certificate procurement can take time, so start early.
- Share your onboarding details with Nedap MediKIT so client credentials and organization scope can be configured for your environments.
- Plan for certificate rotation before expiry so your integration keeps working.
- Confirm your OAuth 2.0 client credentials and organization IDs for the target environment (see Authentication and Onboarding).