Implementation notes

Required software components

An application that connects to this API needs:

• An HTTPS client. All requests must use HTTPS.
• An OAuth 2.0 authorization-code implementation with PKCE (S256).
• An OpenID Connect / JWT library able to verify RS256 signatures against the server's published JSON Web Key Set, if the application validates ID tokens or access tokens.
• For private_key_jwt clients and backend services: the ability to sign a JWT with a private key whose public key you publish. The server accepts RS256/384/512, PS256/384/512, ES256/384/512 and EdDSA signatures on client assertions.
• A FHIR R4 JSON parser; for bulk data, an NDJSON reader.

Required configuration

• Redirect URIs must be registered exactly; a request with any other redirect URI is refused.
• aud on every authorization request must be the FHIR base URL.
• JWK Set URL (asymmetric clients): serve it over HTTPS with accurate Cache-Control headers. PrevHealth never reuses a key set beyond the lifetime you declare, and caps reuse at 5 minutes.
• Clock: keep the application's clock synchronised (NTP); client assertions are time-limited.
• Browser-based applications must be served from an origin that PrevHealth allows for cross-origin requests; give the origin when you register. Discovery documents are readable from any origin.
• Granted scopes: the user may grant fewer scopes than requested. Read the scope value in the token response and degrade gracefully.
• Refresh tokens: store the newest refresh token after each refresh; the previous one is replaced.

TLS

[TO BE CONFIRMED BEFORE PUBLICATION — see OPEN-ITEMS.md: state which component terminates TLS, the minimum version it accepts (1.2 or higher), and how connections below 1.2 are refused.]

Service base URLs

PrevHealth publishes the FHIR service base URL of each organization it serves as a FHIR Bundle (type collection) of Endpoint and Organization resources:

GET https://clinic.prevhealth.us/fhir/service-base-urls

No token is needed. Each Organization carries its name, address and identifiers and references its Endpoint through Organization.endpoint; each Endpoint.address is a FHIR base URL.

Registering an application

[TO BE CONFIRMED BEFORE PUBLICATION — see OPEN-ITEMS.md: the channel developers use to request registration (address or form), and the expected turnaround.]

Provide the attributes listed in Authorization.

Additional data

Beyond the US Core resources, the server also serves Endpoint, Questionnaire, Group (bulk export) and Provenance. Where a record has no source data for a US Core element, the element is omitted rather than filled with a placeholder.

Terms and conditions

[TO BE CONFIRMED BEFORE PUBLICATION — see OPEN-ITEMS.md: link to the API terms and conditions. Required by the API Conditions of Certification (§170.404(a)(2)).]