Electronic Prior Auth | Medplum

On this page

Alpha

Medplum CMS-0057-F Electronic Prior Auth is currently in alpha.
This document describes the recommended process for establishing connectivity and beginning CRD (Coverage Requirements Discovery) testing with Medplum.
The goal is to help implementation partners get to a successful first CDS Hooks exchange as quickly as possible.

Overview

Medplum supports CMS-0057-F connectivity and testing using:

CDS Hooks
OAuth2 Client Credentials
OAuth2 JWT Client Assertion (JWKS)
Optional mTLS

Our staging environments are intended for interoperability and conformance testing with payer and provider partners.

Environment Endpoints

CDS Hooks Base URL

Standard:

https://api.staging.medplum.dev/cds-services

mTLS:

https://mtls.api.staging.medplum.dev/cds-services

OAuth2 Token Endpoint

Standard:

https://api.staging.medplum.dev/oauth2/token

mTLS:

https://mtls.api.staging.medplum.dev/oauth2/token

Supported Authentication Methods

Medplum supports the following OAuth2 client authentication methods:

Method	Supported
`client_id + client_secret`	Yes
JWT Client Assertion (`private_key_jwt`)	Yes
mTLS	Optional

For initial testing, we generally recommend starting with:

client_id + client_secret

This minimizes setup complexity and helps isolate connectivity issues before introducing JWKS or mTLS.

Client Registration Information

To establish connectivity, partners should provide:

For Client Secret Authentication

Preferred client name
Redirect/contact information if applicable

For JWT Client Assertion

Issuer URL
JWKS URI

Example:

Issuer:

https://partner.example.com

JWKS:

https://partner.example.com/.well-known/jwks.json

For mTLS

Please provide:

Client certificate
Certificate chain (if applicable)
Expected TLS configuration details

Important CDS Hooks Discovery Requirement

Before invoking any CDS Hooks service, clients MUST first retrieve the CDS service discovery document:

GET /cds-services

Example:

GET https://api.staging.medplum.dev/cds-services

The response contains a list of available CDS services.

Each service has:

id
hook
additional metadata

Important

The CDS Hooks hook name is NOT the same as the service endpoint path.

Incorrect:

POST /cds-services/order-sign

Correct:

POST /cds-services/{service.id}

Workflow:

Call GET /cds-services
Find the service matching your desired hook
Invoke using the returned service.id

Example CRD Flow

Step 1 — Discover Services

GET /cds-services

Authorization: Bearer {token}

Step 2 — Find Desired Hook

Example service:

{
  "hook": "order-sign",
  "id": "6f1869c9-e217-4225-9047-bbbc5499f35b"
}

Step 3 — Invoke Service

POST /cds-services/6f1869c9-e217-4225-9047-bbbc5499f35b

Content-Type: application/json

Authorization: Bearer {token}

CDS Hooks Payload Guidance

Stable Identifiers

During testing, some systems dynamically generate transient resource IDs. To improve interoperability, Medplum recommends preserving stable identifiers where possible, especially:

Patient.id
Patient.identifier
Coverage/member identifiers

In practice, payer systems often need stable identifiers to determine which mock/test scenario should be returned.

Coverage Data

Coverage information should be included using standard CRD prefetch patterns. Recommended:

"prefetch": {
  "coverageBundle": {
    "resourceType": "Bundle",
    ...
  }
}

Avoid relying on non-required fields unless explicitly agreed upon between partners.

Expected Response Format

Successful responses typically resemble:

{
  "cards": [],
  "systemActions": []
}

An empty cards array may still indicate a successful invocation.

Error Handling

Medplum returns standard FHIR OperationOutcome resources for many error conditions. Example:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found"
    }
  ]
}

Many responses also include tracing metadata extensions:

requestId
traceId

Please include these identifiers when reporting issues.

Environment Expectations

Availability

The staging environment is generally available 24/7. However:

it is not SLA-backed
test data may occasionally be reset
mock payer logic may evolve during testing cycles

Partners should expect occasional non-production instability.

Recommended Testing Sequence

We recommend the following onboarding order:

Verify OAuth token acquisition
Verify GET /cds-services
Verify CDS Hooks invocation
Validate CRD payload structure
Introduce JWT assertions if desired
Introduce mTLS if required
Run full CMS-0057-F scenarios

Troubleshooting Checklist

404 Errors

Common causes:

Posting directly to /cds-services/{hook}
Incorrect service ID
Expired/reset staging data

Empty Responses

Possible causes:

Test scenario identifiers not preserved
Missing or incomplete patient/coverage data
Mock payer unable to determine expected scenario

Authentication Failures

Verify:

Token endpoint URL
JWKS reachability
JWT issuer alignment
OAuth scopes
mTLS certificate configuration

Support & Coordination

If issues arise during testing, please provide:

Full request payloads
Response payloads
Request IDs / trace IDs
Timestamp of request
Whether traffic was routed through the Drummond proxy

Scheduling live troubleshooting sessions is often the fastest way to resolve interoperability issues.