Production Integration Documentation

Platform Overview

Integration Architecture

Environment Separation & JWKS

Authentication Flow (Backend Services)

Initial requested scopes (App Orchard submission)

Default Patient FHIR Reads (code-aligned)

Bulk FHIR & other APIs

Epic write scopes — not requested at initial deployment

• Observation.Create (code only)Would require write scopes + DAMAROS_FHIR_WRITE_ENABLED + production attestation; not activated in initial submission
• Subscription.Create (code only)Same write gates; not part of initial connector

Future / site-specific scope requests (not default bundle)

Clinical data boundary (enforcement, not policy-only)

• Cohorts are defined by approved protocol logic or institutional configuration.
• Patient data is retrieved through FHIR read APIs or, only when explicitly enabled, Bulk FHIR export—per site policy and §03B.
• PHI is processed inside the institution-approved deployment boundary (VPC / tenant isolation per deploy contract).
• Protocol assistance (outside the screening execution path): Criterion PASS / REVIEW / FAIL comes only from the deterministic engine on ingested FHIR—protocol assistance is not on that hot path. Where enabled at all, it is optional, uses non-patient protocol or synopsis text only, and sits behind deployment flags and pattern guards. Patient-facing narrative assistance stays off by default.
• Technical controls (code-aligned): separation of protocol-facing modules from FHIR ingest paths; hard validation rejecting known PHI patterns in protocol-assistance payloads; structured audit signals on boundary violations.
• Default egress posture for this Epic integration: no transmission of patient-identifiable data or cohort-row clinical payloads to third-party assistance endpoints for screening—the deterministic path never requires it. No patient identifiers and no cohort-linked fields are serialized into any optional external request path, even when protocol assistance is enabled—only free-standing protocol or synopsis text passes those guards. Optional outbound use of that non-patient text exists only where deployment policy explicitly enables it and network paths allow it; default hospital deployments keep it off.
• Network enforcement (deploy-time): Helm ships deny-by-default API egress NetworkPolicy with explicit CIDR allowlists for Epic FHIR, OIDC, in-cluster Postgres/Redis, and DNS—see §08 sample. Customer CNI must enforce; IT validates with pod-level denial checks per deployment runbook.
• Eligibility outputs are criterion-level PASS, REVIEW, or FAIL with evidence references where populated—never an ungrounded generative verdict.
• Audit artifacts preserve source FHIR references where available for reconstruction.

Audit, Determinism, and Replay

• Decisions are reproducible for fixed protocol version, cohort snapshot, evidence snapshot, and evaluation_as_of.
• Every patient outcome is recorded at criterion level with PASS, FAIL, or REVIEW and rationale.
• Protocol amendments link to versioned protocol IDs and engine versions.
• Replay classifies agreement or divergence; no opaque “model decided” eligibility.

Identity, attribution, and access control

• Epic layer: Backend Services uses a registered client credential (service identity). FHIR access is attributable to that Epic app registration and institutional consent—not to an individual end-user OAuth token on the screening hot path. There is no Epic “user impersonation” model on this connector: the app does not obtain on-behalf-of-clinician delegated scopes.
• Application layer — who triggered the pull: interactive cohort / EHR sync is invoked via authenticated API routes (e.g. POST /v1/integrations/ehr/sync): the request is authorized with RBAC (workflow_update on the org) after principal_from_request resolves the caller’s subject and org. Scheduled automation may instead use an org-scoped DAMAROS_EHR_SYNC_TRIGGER_TOKEN bearer (no human session)—that path is explicitly service-to-service, not a hidden user identity. The token value lives only in a secret manager (or equivalent), is rotatable on demand, and each enqueue / trigger emits an auditable log_event line with org and job outcome. It grants no broader API privileges: it is accepted only as Bearer on POST /v1/integrations/ehr/sync and cannot enqueue unrelated jobs or call other routes.
• Correlating Epic traffic to application audit: successful persisted ingests receive a durable cohort_sync_run_id carried into screening and review rows; connectivity or no-op checks are logged without creating downstream cohort mutation records.
• Coordinators and staff use identity-backed sessions (JWT / OIDC per deployment). Principals carry subject, role, organization scope, and trial scope; administrative and export actions remain RBAC-gated; web sessions are TTL-bound.
• Summary for IT: Epic audit trails reflect the Backend Services app; Damaros audit trails reflect the signed-in principal (or declared automation token) plus cohort_sync_run_id—together they answer “which institution, which ingest, which human action” without conflating the two layers.

Write-back controls (defense in depth)

• Epic write scopes are not requested for initial deployment (see §03C).
• Write helpers are off by default at the code level in every environment.
• Non-production: DAMAROS_FHIR_WRITE_ENABLED=1 only after explicit site policy may enable write helpers for sandbox testing.
• Production: requires DAMAROS_FHIR_WRITE_ENABLED=1 and DAMAROS_FHIR_PRODUCTION_WRITE_ATTESTED=1 when DAMAROS_ENV is production-class—two independent signals so a single typo cannot enable EHR mutation during audit.

Performance and API Usage

• FHIR usage follows Epic operational guidance; iterative reads are the default. Bulk export is used only where §03B gates are satisfied.
• Rate limiting and bounded exponential backoff on 429/5xx.
• Per-resource failures in a bundle do not block other resource types in the same pull.

Error Handling and Resiliency

• Missing clinical data surfaces as REVIEW where appropriate—not silent PASS.
• Retry paths are idempotent while write-back remains disabled.

Security, privacy, and logging

• Signing keys and Epic access tokens are server-side secrets; FHIR and browser traffic use TLS.
• Logging posture: structured logs favor stable identifiers (request id, org id, trial id, non-PHI codes). Field-level exclusion lists omit free-text clinical narrative from default log templates; high-sensitivity routes use reduced payloads. Operators may attach SIEM classification tags (e.g. security vs. workflow) per deployment. Full request or response body logging for FHIR traffic is not a default product posture.
• Data at rest encryption and retention follow deployment architecture and the customer BAA / DPA.

Review artifacts (non-production samples)

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: damaros-api-egress
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/component: api
  policyTypes: [Egress]
  egress:
    - ports: [{port: 53, protocol: UDP}, {port: 53, protocol: TCP}]
      to:
        - namespaceSelector:
            matchLabels: {kubernetes.io/metadata.name: kube-system}
    - ports: [{port: 443, protocol: TCP}]
      to:
        - ipBlock: {cidr: 203.0.113.0/24}   # resolve & replace: Epic FHIR + token host CIDRs
    - ports: [{port: 5432, protocol: TCP}]
      to:
        - podSelector:
            matchLabels: {app.kubernetes.io/component: postgres}

This shape reflects the enforced default when the chart’s networkPolicy.enabled (and related egress blocks) are left on—IT should treat it as the shipped baseline, not decorative documentation. Full template: deploy/helm/damaros/templates/networkpolicy.yaml in the product repo—includes Redis, OIDC, and optional extra HTTPS CIDRs.

{
  "keys": [{
    "kty": "RSA",
    "use": "sig",
    "alg": "RS384",
    "kid": "example-hospital-prod-2026",
    "n": "w9zY…BASE64URL_TRUNCATED…q8Q",
    "e": "AQAB"
  }]
}

# header (base64url-decoded for readability)
{ "alg": "RS384", "typ": "JWT", "kid": "example-hospital-prod-2026" }

# claims
{
  "iss": "epic-backend-services-client-id-example",
  "sub": "epic-backend-services-client-id-example",
  "aud": "https://fhir.epic.com/interconnect-nonprod-oauth/oauth2/token",
  "jti": "2f5b0c1a-9e3d-4b7a-8f1c-0d2e4a6b8c0e",
  "exp": 1710000300,
  "iat": 1710000000
}

{"ts":"2026-04-01T12:00:00.000Z","event":"integrations.ehr_sync.triggered","org_id":"org_***","principal_sub":"oidc|coordinator_***","damaros_role":"coordinator","epic_oauth_client_id":"epic-backend-services-client-id-***","cohort_sync_run_id":"csr_7f2a9b1c***","ok":true}

Each such record corresponds to one discrete EHR sync execution (coordinator UI action or automation token)—mappable to “who kicked off this pull” in plain language. Production lines follow your SIEM schema; Epic records the same Backend Services client_id on token issuance. The JSON above is a review packet composite (fields may span log_event + domain event)—not one verbatim syslog line.

Contact