Authentication and access

Open Aidn APIs require OAuth 2.0 bearer tokens issued for the approved integration. Access is controlled by client configuration, tenant configuration, and endpoint-specific scopes.

OAuth client authentication

Most system-to-system integrations use a confidential OAuth client with private_key_jwt client authentication.

The client needs at least one key pair. This can be handled in either of two ways:

• The vendor generates a key pair and sends only the public key to the municipality or Aidn administrator for registration in the admin portal.
• The municipality or Aidn administrator generates the key pair in the admin portal and securely transfers the private key to the vendor.

Your integration keeps the private key in its own secure secret store and uses it to sign token requests.

If the admin portal generates the key pair, the private key is shown only once and cannot be retrieved later. Store it before closing the dialog.

Never commit private keys to source control, include them in logs, or share them over email or chat.

Scopes

Scopes limit what a client can do. A client can only request scopes that were configured for that client.

Open Aidn uses scope names inspired by SMART on FHIR. For example, the EpisodeOfCare search endpoint requires:

Scope	Purpose
episodeofcare.search	Search for EpisodeOfCare resources.
episodeofcare.read	Read one EpisodeOfCare resource by ID.

The exact scopes for an integration are agreed as part of onboarding and should match the approved use case.

Calling Open Aidn APIs

Each API request must include the access token in the Authorization header:

Authorization: Bearer <ACCESS_TOKEN>
Accept: application/fhir+json

Requests and responses use FHIR JSON where applicable. Search endpoints return a FHIR Bundle with type set to searchset.

Compliance and data minimization

Open Aidn integrations must follow the agreed purpose and data scope for the municipality. As an integration partner, you are expected to:

• Request only the scopes required for the approved use case.
• Store credentials and tokens securely.
• Avoid persisting healthcare data unless this is part of the agreed processing purpose.
• Log access in a way that supports troubleshooting without exposing unnecessary health information.
• Coordinate key rotation and incident handling with the municipality and Aidn.

Aidn applies authentication, authorization, tenant configuration, and audit mechanisms on the platform side. These controls do not replace the vendor’s responsibility to protect credentials and handle health data according to the agreement.