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 stores the private key securely and uses it to sign token requests.

If the admin portal generates the key pair, the private key is shown only once and can’t 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.

Client assertions with private_key_jwt

With private_key_jwt, the OAuth client does not send a client secret. Instead, the client creates a short-lived JWT called a client assertion, signs it with the registered private key, and sends it to the OAuth token endpoint as part of the token request.

The token request should include these form parameters:

audience=urn:open.aidn.no
grant_type=client_credentials
client_id=<CLIENT_ID>
scope=<SPACE_SEPARATED_SCOPES>
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<SIGNED_JWT>

The signed JWT should identify the OAuth client and the authorization server:

iss: the OAuth client ID.
sub: the OAuth client ID.
aud: the OAuth issuer base URL for the environment, not the token endpoint URL.
iat: the time the assertion was issued.
exp: a short expiry time for the assertion.
jti: a unique value for this assertion.
typ: client-authentication+jwt

The JWT header must include the signing algorithm (alg). If a key ID (kid) was provided during client setup, include it in the JWT header so the authorization server can identify the registered public key used to verify the assertion.

Set the aud claim to the issuer base URL listed below. Do not use /connect/token as the audience. For example, use https://health.auth.demo.aidn.no for demo, not https://health.auth.demo.aidn.no/connect/token. This follows the updated audience guidance in RFC 7523bis, which requires the authorization server issuer identifier as the audience for JWT client authentication assertions.

Environment URLs

Use the URLs for the environment where your integration is enabled. The FHIR base URL is the root for FHIR requests. Append resource paths such as Patient or EpisodeOfCare.

Environment	FHIR base URL	OAuth issuer base URL	OAuth token endpoint
Demo	`https://open.demo.aidn.no/fhir`	`https://health.auth.demo.aidn.no`	`https://health.auth.demo.aidn.no/connect/token`
Production	`https://open.aidn.no/fhir`	`https://health.auth.nhn.aidn.no`	`https://health.auth.nhn.aidn.no/connect/token`

Request tokens from the token endpoint using the OAuth client credentials and private_key_jwt setup provided for your integration. Use demo credentials only with the demo environment, and production credentials only with production.

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 don’t replace the vendor’s responsibility to protect credentials and handle health data according to the agreement.

Back to home