In short
- Oracle Health exposes Millennium data through FHIR R4 APIs that you register for in code Console, test first in a read-only open sandbox and then in an authenticated secure sandbox.
- Authorization follows SMART App Launch 1.0.0 and SMART Backend Services 1.0.1, with details that trip teams up: no wildcard scopes, a required aud parameter, access tokens of 570 seconds and refresh tokens that are not reissued.
- Going live is a per-customer step: the health system provisions your production client ID against its tenant through separate service requests, and may need a PECA form, Citrix trusted sites and SMART setup in PowerChart.
To build on the Oracle Health (formerly Cerner) FHIR API, you register your app in code Console, prototype against the read-only open sandbox, test authorization and every declared scope in the secure sandbox, and then have each health system provision your production client ID against its own Millennium tenant. The APIs are HL7 FHIR R4, protected with SMART App Launch and SMART Backend Services. Oracle tells developers to build for R4 because DSTU 2 is being retired.
The details in Oracle's documentation that most often cost teams a week are the sandbox URLs, scope rules, token behavior, system accounts and the provisioning requests a customer has to file. Oracle updates its documentation often, so check the linked pages before you write code.
What APIs does Oracle Health offer on Millennium?
Oracle's documentation describes the FHIR R4 APIs as letting a registered user access the Oracle Health EHR data in the Millennium Platform for which they are authorized. The R4 guide includes a list of REST endpoints by resource. Oracle also publishes Bulk Data Access for population-level exports, covered below. If you find older DSTU 2 code or examples, Oracle's build guide is direct: develop your application for R4, as DSTU 2 is being retired.
How do you register an app?
Registration happens in code Console, Oracle's developer portal. Code Console requires a CernerCare account, which you can create the first time you use it. When you create an application there, Oracle says you are creating it against the production cloud environment associated with a production-level Millennium environment. Code Console gives you the application ID, client ID and application name that each customer will later need.
Registration is also where you choose the app type. Oracle's authorization documentation says system accounts are issued when you register an app as type System or with Confidential privacy, and that confidential client applications receive secrets managed through Cerner Central system accounts.
Which sandbox should you use?
Oracle runs two sandbox modes on the same sandbox tenant, ec2458f2-1e24-41c8-b71b-0e701af7583d:
- Open sandbox: https://fhir-open.cerner.com/r4/{tenant}/. No authentication. Oracle recommends it for initial proofs of concept and integration. It is read-only: no writes are available in the sandbox without authentication.
- Secure sandbox, non-patient: https://fhir-ehr-code.cerner.com/r4/{tenant}/. For testing provider and system access with authorization and all your declared scopes.
- Secure sandbox, patient access: https://fhir-myrecord.cerner.com/r4/{tenant}/. The service root differs when a patient or a patient's proxy is logging in.
For provider-facing apps, Oracle says you can pick any patient from the sandbox patient list in code Console and open your app from a new browser window. One warning from the service root page applies everywhere: no IDs or identifiers in Millennium are meant to be used outside the context of their complete URL. Store the full reference, not a bare ID.
How does authorization work?
Oracle states that its FHIR implementation is protected using the SMART App Launch Framework and SMART Backend Services, and lists HL7 SMART Application Launch 1.0.0 (STU1) and SMART Backend Services 1.0.1 (STU1) as the supported versions. Some pages link to newer SMART material, so confirm with Oracle before relying on SMART v2 behavior. The rules that matter most in practice:
- Discover endpoints, do not hard-code them. Call {FHIR base}/.well-known/smart-configuration to get the authorization, token, revocation and introspection endpoints. Oracle says these URLs can change.
- Always send aud. The authorization server automatically rejects authorization requests without the audience parameter. scope and state are required too.
- Request each scope by name. Oracle does not support wildcard scopes, and the * permission is not supported.
- Use v1-style scopes: user/, patient/ or system/ context, then the resource, then read or write, for example user/Observation.read.
- Patient scopes need a launch flow. For patient-facing apps, Oracle notes its server does not support the stand-alone OpenID workflow.
- For EHR launch, your app receives iss and launch parameters and must include launch (or launch/patient, launch/encounter) in its scope.
- Use TLS 1.2 or 1.3, and do not run the authorization flow inside an iframe.
What should you know about tokens?
Millennium apps often break after go-live because of token handling. Oracle documents these behaviors:
- The default access token is valid for 570 seconds, about ten minutes.
- online_access gives a refresh token that lasts during the user's authenticated session and ends on logout or session termination.
- offline_access gives a refresh token that lasts until revoked, but access is revoked if your application goes unused for more than three months.
- A refresh response does not contain a new refresh token. Keep the one from the initial grant.
- Refreshing at intervals below one minute may be throttled. Oracle recommends fetching and caching a new token before the old one expires.
- A refresh token can be suspended if your TLS or DNS information changed since the original authorization, for example after a certificate expires.
Build a token service that refreshes on a timer a little before expiry, stores the original refresh token safely, and alerts your team when a refresh fails instead of silently logging users out.
How do backend and system integrations authenticate?
For server-to-server work with no user present, Oracle describes two client credentials modes. Basic authentication uses a system account ID and secret, Base64-encoded, requesting system/ scopes. JWT authentication uses signed JWTs, and Oracle names it the appropriate mode for Bulk Data Access. JWT clients preregister their JWKS through Cerner Central System Account Management.
Two rules from the same page: system/ scopes must not be combined with other contexts, and online_access or offline_access must not be used with the client credentials flow. Oracle also notes that system access is only supported on resources where the resource documentation explicitly says so, so check each resource you plan to call.
What if your app launches inside PowerChart?
Clinician-facing SMART apps usually open from PowerChart, Millennium's clinician application. Oracle's build guide says that if you plan to use SMART to open your app from PowerChart with a patient selected, your launch must support both access points: the PowerChart table of contents and an MPages component embedded in PowerChart. Test both. They behave differently in window size and in how users get back to the chart.
How does a health system turn your app on?
Oracle's provisioning guide describes the customer side, and it is mostly service requests (SRs) the health system files with Oracle. The developer's job is to hand over the production application ID, client ID and app name from code Console, plus any external website dependencies. The customer then:
- Gets its tenant ID, from Oracle Health Hosting or from Cerner Central depending on its hosting model.
- Files an SR asking for your application ID and client ID to be provisioned against that tenant, and for hosted production, requests the FHIR URL.
- Completes a Process for Executing Client Approval (PECA) form, if applicable, for production.
- For non-production, files an SR to map the codable concepts your app uses.
- Adds your external website dependencies to its Citrix trusted sites, if applicable.
- Completes the SMART application setup so the app runs in PowerChart or FirstNet, if applicable.
Oracle says each of these must be a separate SR and topics must not be combined. Production base URLs follow the pattern https://fhir-ehr.cerner.com/r4/{tenant ID}/, with regional hosts for Asia-Pacific, Canada and the UK. Oracle also notes that self-service provisioning does not apply to CommunityWorks, PowerWorks or Continuum (shared domain) customers unless it fits Oracle's Minimum Viable Strategy, so ask early which model your customer is on.
Can you pull population data in bulk?
Yes, through Oracle's Bulk Data Access, which it describes as letting system applications access large volumes of core clinical data for a group of individuals in line with 21st Century Cures Act standards. Oracle supports Group export based on version 1.0.1 of the FHIR Bulk Data Access guide, with some experimental parameters from 2.0.0, and Patient export based on version 2.0.0. Patient export does not support exporting all patients: you must pass a list of patient IDs.
- Register a Millennium Bulk Data SMART application in code Console. Open endpoints do not support bulk export.
- Work with the health system to identify which groups you may export. Organizations manage groups in Ignite Management Tooling.
- Plan for load. Oracle notes that bulk data runs against the organization's database and uses the same services as other applications.
- Handle HTTP 429 throttling, and use the Prefer: handling=lenient header if you want unsupported parameters ignored instead of rejected.
What slows Oracle Health projects down?
- Starting in the open sandbox and never moving on. It is read-only and unauthenticated, so writes, scopes and token expiry go untested.
- Assuming a scope works for system access because it works for users. Check each resource page.
- Waiting on SRs. Each provisioning step is a separate request on the customer's side, and your timeline depends on how fast its team files them.
- Hidden web dependencies. Fonts, analytics or identity pages your app loads from other domains may need to be on the customer's Citrix trusted sites.
- Token refresh bugs that only show up after ten minutes, or after three months of inactivity.
For any vendor platform, including Oracle Health, we work from the vendor's documentation and sandbox, and we have shipped Epic and athenahealth integrations. We sign a BAA before anyone on our team sees PHI and run a penetration test before launch. If you are planning a Millennium integration, talk to one of our engineers. Our free five-day technical audit ends with a written report on your scopes, launch points and provisioning plan.