Skip to main content

Authentication and Onboarding

This guide describes what a vendor needs to start using the MediKIT API with OAuth 2.0 client credentials and organization-scoped access.

What you receive during onboarding​

Nedap MediKIT provides:

  • CLIENT_ID
  • CLIENT_SECRET (via secure channel)
  • TOKEN_ENDPOINT
  • API_BASE_URL
  • Assigned ORGANIZATION_ID values

For the API base URL, use the host for your target environment. The hosts and their certificate requirements are listed in Environments and PKIoverheid certificates.

Example request path: /v2/{organizationId}/fhir/R4/Patient/{id}.

Acceptance and production require a PKIoverheid (PKIO) client certificate. Build against your own mock of the API and verify your integration on acceptance. See Environments and PKIoverheid certificates for the per-environment requirements.

Authentication flow​

  1. Request an access token at TOKEN_ENDPOINT using client_id and client_secret.
  2. Use the returned Bearer token for API requests.
  3. Refresh before expiry.

Access model (roles + organizations)​

Access is determined by both:

  • Role entitlements assigned to your client (which operations/resources are allowed)
  • Allowed organizations assigned to your client (which organizationId values are allowed)

A request is only allowed when both role and organization checks pass.

Verification checklist​

After onboarding, validate your setup:

  1. Get a token with your credentials.
  2. Call an endpoint for an assigned ORGANIZATION_ID (expect success).
  3. Call the same endpoint for an unassigned ORGANIZATION_ID (expect denial).
  4. Call one endpoint within your expected role scope (expect success).
  5. Call one endpoint outside your role scope (expect denial).

Security requirements​

  • Keep client secrets in a secure secret manager.
  • Never log or share raw Bearer tokens.
  • Rotate credentials immediately if compromise is suspected.