Cerner
Oracle Health (Cerner)
Cerner
Complete OAuth 2.0 and FHIR R4/STU3 integration adapter for Oracle Health (Cerner) EHR systems. Supports patient-facing, system-to-system, and embedded EHR launch workflows with full FHIR resource operations and bulk data export.
Overview
ConnectHealth's Cerner integration gives your application secure access to patient data and clinical workflows through Oracle Health (Cerner)'s OAuth 2.0 and FHIR R4 APIs. ConnectHealth acts as the middleware layer — handling authentication, SMART endpoint discovery, token lifecycle, and FHIR communication — so your team can focus on building features rather than managing Oracle Health-specific OAuth flows.
You (your organization) must create and own Oracle Health (Cerner) applications. ConnectHealth is middleware — it does NOT create apps, manage Oracle Health Code Console accounts, or submit applications on your behalf, so you must have an approved Oracle Health application with a Client ID before configuring any workflow in ConnectHealth.
On This Page
Supported Authentication Flows
Click a card to jump to its configuration section.
Standalone OAuth
Standard OAuth 2.0 authorization code flow where users authorize access to their data via the Cerner patient portal. Best for patient portals, health tracking apps, and third-party apps needing patient consent.
Backend to Backend (B2B)
JWT Bearer assertion flow for server-to-server authentication without any user interaction. Best for automated data sync, population health analytics, and background processing.
Embed Launch
SMART on FHIR launch flow for applications embedded within Cerner's interface (PowerChart). The app receives patient and encounter context automatically. Best for clinical decision support and tools.
Key Features
- FHIR resource CRUD operations
- Bulk data export capability
- SMART endpoint auto-discovery (auth/token URLs derived from the FHIR base URL)
- JWT Bearer assertion for B2B (RSA key pair managed by ConnectHealth)
- Token refresh handling
- Audit logging for all operations
Before You Begin
Before using Oracle Health (Cerner) with ConnectHealth, you must set up an application in the Oracle Health Developer Portal. This section outlines the prerequisites and gives you a step-by-step guide.
Prerequisites Checklist
- Developer account — Create an account at oracle.com/health/developer under your organization's email domain
- Registered application — Created in the Code Console with a Client ID
- Redirect URI registered — Your ConnectHealth callback URL registered in the Code Console (for Standalone and Embed Launch)
- For B2B: JWKS URI registered — Copy the JWKS URI from ConnectHealth and paste it into your System Account app in the Code Console
- For production — A separate production review by Oracle Health, and activation by the local hospital customer's IT admin within Millennium
Create Your Cerner Application
Follow these steps to create your Oracle Health (Cerner) application in the Code Console. Your organization owns and manages this app — the Code Console is where you'll manage credentials and scopes.
Create an Oracle Health Developer Account
If you don't already have one, create an account at the Oracle Health Developer Portal (Code Console).
- Sign up using your organization's email domain
- Your organization will own this account and all apps created under it
- Keep your login credentials secure
Create a New Application in Code Console
In the Code Console, register a new application and choose the app type that matches your workflow:
- Click New App in your Code Console dashboard
- Choose your application type:
- For Standalone (patient-facing): Select Patient (Standalone Launch)
- For Backend (B2B): Select System (Client Credentials with JWT assertion)
- For Embed Launch (in-EHR): Select Provider (EHR Launch via PowerChart)
- Enter an app name and description
- Select the exact FHIR scopes your application requires. You cannot change scopes dynamically without updating the app configuration in Code Console first.
Configure URIs and Copy Client ID
After creating your app, copy your Client ID and configure the required credential fields in the Code Console:
- Copy the Client ID generated by Oracle Health.
- For Standalone and Embed Launch: Register the Redirect URI (OAuth callback URL) from ConnectHealth:
https://your-connecthealth-domain/api/workflow/auth/{integrationId}/callback
(You will get the exact {integrationId} from ConnectHealth after creating your connection) - For Embed Launch: Register the Launch URI:
https://your-connecthealth-domain/api/workflow/auth/{integrationId}/launch - For B2B (Backend): Copy the JWKS URI from your ConnectHealth connection settings and paste it into the JWKS endpoint field in your app configuration.
- Click Save
Wait for Sandbox Propagation
Any time you create an application, modify scopes, or update redirect URIs in the Oracle Health Code Console, you must wait approximately 15 minutes for those changes to propagate to the Cerner Sandbox. If you test your connection immediately after saving, you will likely receive a 401 Unauthorized or scope validation error — do not troubleshoot until the 15 minutes have passed.
Configure in ConnectHealth
Once propagation is complete, configure your Cerner connection in ConnectHealth:
- Navigate to Connections and create a new connection
- Select Cerner as the EHR type
- Select your workflow type (Standalone, Backend, or Embed Launch)
- Paste your Client ID
- Fill in the FHIR Base URL for the Cerner Sandbox (see Sandbox Environment Setup below)
- For B2B: Ensure the ConnectHealth-generated JWKS URI corresponds to what you registered in the Code Console.
- Save your connection
Test with Sandbox Data
Test your integration using the Oracle Health sandbox credentials.
- For Standalone: Initiate OAuth and log in using the sandbox patient credentials (
nancysmart/Cerner01) - For Backend: Request a system token and test FHIR calls against the Cerner sandbox FHIR base URL
Production App (When Ready)
Oracle Health production access has two distinct gates:
- Submit a separate production-targeted app in the Code Console to undergo a formal technical review by Oracle Health.
- Your hospital customer's IT administration must independently approve and install your integration on their Millennium instance.
The production URL is not global — each hospital customer runs their own Millennium instance, so you must work with the client's IT team to get their specific production FHIR Base URL.
Note: When migrating, you will first connect to your hospital's non-production environment (often called CERT or MOCK in Cerner environments) before receiving final approval for PROD.
See the Oracle Health Developer Portal for detailed production validation and onboarding manuals.
Sandbox Environment Setup
Oracle Health provides a public sandbox to test implementations. You need your own registered application from the Code Console to use the authenticated sandbox endpoints.
Cerner Sandbox Endpoints
| Purpose | URL |
|---|---|
| FHIR Base (Authenticated R4) | https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d |
| OAuth Authorization | https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/protocols/oauth2/profiles/smart-v1/personas/patient/authorize |
| OAuth Token | https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/protocols/oauth2/profiles/smart-v1/token |
| SMART Configuration | https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/.well-known/smart-configuration |
ConnectHealth auto-discovers the Authorization and Token URLs from the SMART Configuration endpoint if supported — in most cases you only need to enter the FHIR Base URL.
Test Patient Data
- Tenant ID:
ec2458f2-1e24-41c8-b71b-0e701af7583d - Patient IDs:
12724066,12724067,12724068,12724069,12724070 - MyChart/Portal Test Login: Username
nancysmart/ PasswordCerner01
Sandbox vs Production Comparison
| Aspect | Sandbox | Production |
|---|---|---|
| FHIR Base URL | fhir-ehr-code.cerner.com/r4/[sandbox-tenant-id] |
Customer-specific (e.g., fhir-myrecord.cerner.com/r4/[client-tenant-id]) |
| App Approval | Code Console registration (15 minute propagation limit) | Oracle Health Validation Review + hospital IT authorization |
| Data | Synthetic test patients only | Real patient data (HIPAA-covered) |
| Credentials | Sandbox Client ID | Separate production Client ID targeting production environment |
| Approval Timeline | 15 minutes | Weeks to months (Oracle validation queue) |
Configuration Reference
Complete Steps 1–4 above (create your app in the Code Console and wait for propagation) before filling in these fields.
Standalone OAuth
Standard OAuth 2.0 authorization code flow where users authorize access to their data via the patient portal. Best for health tracking apps and patient-facing applications.
| Field | Autofill | Required | Description |
|---|---|---|---|
Client ID |
No | Yes | Your unique application identifier from the Oracle Health Code Console. |
Client Secret |
No | No | Client secret for confidential clients (most apps are public clients and won't need this). |
Authorization URL |
Yes | Yes | Cerner's OAuth authorization endpoint URL. |
Token URL |
Yes | Yes | Cerner's OAuth token endpoint URL. |
Scopes |
No | Yes | Space-separated list of OAuth scopes requested strictly matching those approved in Code Console. |
Redirect URL |
Yes | Yes | Your ConnectHealth callback URL. Must match the URL registered in Code Console exactly. |
FHIR Base URL |
No | Yes | The base URL of the specific Cerner Millennium FHIR server you are connecting to. |
Backend to Backend (B2B)
JWT Bearer assertion flow for server-to-server authentication. ConnectHealth automatically generates and manages the RSA key pair. Best for automated data sync and analytics.
Authentication is done via JWT Bearer assertion. ConnectHealth gives you a JWKS URI — you must copy this URI and register it securely into the System Application configuration in the Oracle Code Console.
| Field | Autofill | Required | Description |
|---|---|---|---|
Client ID |
No | Yes | Your unique application identifier from the Code Console. |
Private Key |
Yes | Yes | Automatically generated RSA private key used by ConnectHealth to sign JWT assertions. |
Token URL |
Yes | Yes | Cerner's OAuth token endpoint URL. |
FHIR Base URL |
No | Yes | The base URL of the Cerner FHIR server. |
Scopes |
No | Yes | Space-separated list of system-level OAuth scopes (e.g., system/*.read). |
SMART on FHIR - Embed Launch
SMART on FHIR launch flow for applications embedded within Cerner PowerChart. The app is launched from within the EHR and receives context automatically.
| Field | Autofill | Required | Description |
|---|---|---|---|
Client ID |
No | Yes | Your application identifier from the Code Console. |
Client Secret |
No | No | Required only for confidential clients. |
How to Handle SMART Launch
Here's the end-to-end flow — from Cerner initiating the launch, to your app receiving a usable FHIR access token.
Cerner Initiates the Launch
When an active user opens your app from within PowerChart, Cerner calls your registered Launch URL:
GET https://<your-ch-domain>/api/workflow/auth/{integrationId}/launch?iss=...&launch=...No action needed from you — this is the URL you registered in the Code Console.
ConnectHealth Completes OAuth and Returns a tokenId
ConnectHealth executes the token exchange, securely stores the payload, and redirects the browser back to your app with a short-lived, one-time-use tokenId parameter in the URL.
Call Token Exchange to Retrieve Access Token
Your app calls the Token Exchange endpoint with the tokenId. Requires the x-api-key header:
GET https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/exchange/{tokenId}
Headers:
x-api-key: <your-connecthealth-api-key>Jump to Get Your ConnectHealth API Key to create one.
Call FHIR Using the Access Token
Use the access_token as a Bearer token against Cerner's FHIR base URL (e.g. Millennium endpoint).
Refresh Before Expiry
POST https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/refresh
Headers:
x-api-key: <your-connecthealth-api-key>
Content-Type: application/json
Body:
{
"refresh_token": "<your-refresh-token>"
}General Scopes
Scopes define the level of access your application requests. Oracle Health strictly enforces scopes requested.
User Scopes
| Scope | Description |
|---|---|
user/*.read | Read all resource types the user has access to |
user/Patient.read | Read patient demographics the user can access |
user/Encounter.read | Read encounter records the user can access |
System Scopes (B2B)
| Scope | Description |
|---|---|
system/*.read | Read all resource types at the system level |
system/Patient.read | Read all patient demographics |
system/Group.read | Read patient groups (required for bulk data export) |
Launch Scopes
| Scope | Description |
|---|---|
launch | Required for EHR launch — receives launch context from Cerner |
launch/patient | Request patient context in a standalone launch |
launch/encounter | Request encounter context in a standalone launch |
Identity Scopes
| Scope | Description |
|---|---|
openid | Required for OpenID Connect — returns an ID token |
fhirUser | Returns the FHIR resource URL of the authenticated user |
offline_access | Request a refresh token for long-lived access |
Use Cases
Choose the workflow type that best matches your application's needs.
Patient-Facing Applications
Scenario: A third-party app needs to access patient health data with the patient's explicit consent.
Recommended Workflow: Standalone OAuth
Best For: Patient portals, health tracking apps, care management tools
Recommended Scopes: patient/*.read openid fhirUser launch/patient offline_access
System-to-System Integration
Scenario: A server needs to access Oracle Health data without any user interaction for automated processing.
Recommended Workflow: Backend to Backend (B2B)
Best For: Nightly data sync, population health analytics, automated reporting
Recommended Scopes: system/*.read
EHR-Embedded Applications
Scenario: An application launched from within Cerner's powerchart workflow that receives patient and encounter context automatically.
Recommended Workflow: Embed Launch (SMART on FHIR)
Best For: Clinical decision support, order entry helpers, documentation assistants
Recommended Scopes: launch openid fhirUser patient/*.read launch/encounter
Bulk Data Export
Scenario: Extracting large datasets from Oracle Health for analytics, research, or population health.
Recommended Workflow: Backend to Backend (B2B)
Best For: Population health reports, research datasets, quality measure reporting
Recommended Scopes: system/*.read system/Group.read
Workflow Automation
Scenario: Low-code Node-RED workflows interacting with Oracle Health for automated data pipelines within ConnectHealth.
Recommended Workflow: Backend to Backend (B2B)
Best For: Automated notifications, data transformation pipelines, integration workflows
Recommended Scopes: system/*.read
Get Your ConnectHealth API Key
Several ConnectHealth endpoints — Token Exchange, Backend Token, and Token Refresh — require a ConnectHealth API key passed as the x-api-key header. Without this header, these endpoints return 401 Unauthorized. Follow these steps to create your API key.
Log in to the ConnectHealth Dashboard
Log into your ConnectHealth instance (the URL where your deployment is hosted).
Navigate to Settings → API Keys
From the left nav, click Settings, then open the API Keys tab.
If you have never generated a key, the list will be empty.
Create a New API Key
Click Create API Key, enter a descriptive name (e.g. cerner-prod-client), and submit.
Under the hood this calls POST /api/keys/ with body { "name": "<your-key-name>" }.
Copy the Key Value
ConnectHealth shows the full API key once — copy it and store it securely (AWS Secrets Manager, Vault, or your secret store).
If lost, you must delete and recreate the key.
Use the Key in the x-api-key Header
All endpoints that exchange or return access tokens require this header.
Header name is exactly x-api-key.
API Endpoints
Token Exchange, Token Refresh, and Backend Token endpoints require the ConnectHealth API Key passed in the x-api-key header.
All API paths are prefixed with your ConnectHealth domain. Replace {integrationId} with the UUID of your Cerner connection.
Token Exchange
Exchange a tokenId for a FHIR access token and launch context parameter.
curl
curl -X GET "https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/exchange/{tokenId}" \
-H "x-api-key: YOUR_API_KEY" \
-H "Accept: application/json"JavaScript (fetch)
const res = await fetch(
`https://<your-ch-domain>/api/workflow/auth/${integrationId}/token/exchange/${tokenId}`,
{ headers: { "x-api-key": process.env.CH_API_KEY, "Accept": "application/json" } }
);
const { access_token, patient, scope, expires_in } = await res.json();Backend Token (B2B)
Generate a B2B system token using JWT Bearer assertion to Cerner.
curl
curl -X GET "https://<your-ch-domain>/api/workflow/auth/{integrationId}/token" \
-H "x-api-key: YOUR_API_KEY" \
-H "Accept: application/json"JavaScript (fetch)
const res = await fetch(
`https://<your-ch-domain>/api/workflow/auth/${integrationId}/token`,
{ headers: { "x-api-key": process.env.CH_API_KEY, "Accept": "application/json" } }
);
const { access_token, scope, expires_in } = await res.json();Token Refresh
Refresh an expired access token without user prompt (requires offline_access scope).
curl
curl -X POST "https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/refresh" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'JavaScript (fetch)
const res = await fetch(
`https://<your-ch-domain>/api/workflow/auth/${integrationId}/token/refresh`,
{
method: "POST",
headers: {
"x-api-key": process.env.CH_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ refresh_token: "YOUR_REFRESH_TOKEN" }),
}
);
const { access_token, refresh_token, expires_in } = await res.json();Response
{
"body": {
"access_token": "eyJhbGc...",
"refresh_token": "dGhpcyBp...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "patient/*.read",
"patient": "patient-id-if-applicable"
},
"message": "Token refreshed successfully",
"timestamp": 1718000000000
}Token Status
Check if an integration token is ready and valid.
curl
curl -X GET "https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/status/{tokenId}" \
-H "Accept: application/json"JavaScript (fetch)
const res = await fetch(
`https://<your-ch-domain>/api/workflow/auth/${integrationId}/token/status/${tokenId}`
);
const { valid, expiresAt } = await res.json();OAuth Start (browser-initiated)
Begin the Standalone OAuth flow. Redirects the user's browser to the Cerner portal.
curl (inspect redirect only)
curl -I "https://<your-ch-domain>/api/workflow/auth/{integrationId}/start"External Resources
- Oracle Health (Cerner) Code Console — Create and manage your Oracle Health applications
- Oracle Health Millennium API Documentation
- Cerner FHIR Documentation
- SMART App Launch Guide
- FHIR R4 Specification