FHIR R4 API for Patient &
Population Services

🔗 Service Base URL

Production FHIR R4 endpoint and server metadata

FHIR R4 Base URL

CapabilityStatement (metadata)

📋 Developer / Application Registration

How to register your application and obtain OAuth credentials

Registration Portal

Registration Procedure for Patient-Facing Applications

Registration Procedure for Clinical User-Facing Applications

system-to-system (B2B) Registration Process

✅ Application Verification & Transparency

Non-discriminatory verification process in accordance with the 21st Century Cures Act and 45 CFR § 170.315(g)(10), and the information blocking regulations and exceptions at 45 CFR Part 171 · Last updated February 9, 2026

In accordance with the 21st Century Cures Act and 45 CFR § 170.315(g)(10), AllegianceMD is committed to a transparent, objective, and non-discriminatory process for verifying third-party applications. We verify applications solely to ensure the security of our platform and the privacy of the patients served by our providers.

1. Verification Scope & Timeline

AllegianceMD reviews all registration requests within 10 business days after receipt of complete submission materials. Our review is limited to technical conformance and security safety. We do not evaluate an application's business model, clinical utility, or competitive status.

2. Technical Conformance Criteria

To be verified for production use, applications must meet the following objective standards:

3. Privacy & Disclosure Requirements

We do not "approve" a developer's privacy practices, but we require transparency so users can make informed choices. All applications must:

4. Performance & Fair Use Standards

To ensure the stability of the healthcare environment, all API clients must adhere to our published rate limits.

5. Non-Discrimination & Appeals

If an application fails verification, AllegianceMD will provide a written Notice of Non-Conformance detailing the specific technical criteria that were not met. Developers are invited to remediate the issues and re-submit for verification at no additional cost. We will respond to resubmissions within 5 business days.

📐 Standards & Technology

Underlying specifications and protocols

🔑 OAuth 2.0 Grant Types

Supported authorization flows for application access

Public vs. Confidential Clients

Confidential clients (able to securely store secrets) may be issued a client_secret for use in authorization grants and token requests.

Public clients (unable to securely store secrets, e.g., native/mobile apps) are not issued a client_secret. They use the Authorization Code flow with PKCE as required by RFC 7636.

Refresh Tokens

Client apps using the authorization code flow may request refresh tokens by including the offline_access scope. Refresh token lifetime defaults to 90 days. Each refresh token may be used once; a replacement is issued upon use. Refresh tokens are not issued for client credentials flows.

⚙️ SMART Configuration Discovery

Discover OAuth endpoints and SMART capabilities programmatically

This endpoint returns a JSON document containing the authorization_endpoint, token_endpoint, supported capabilities, token auth methods, scopes, grant types, and PKCE code challenge methods.

# Retrieve SMART configuration
curl -s -H "Accept: application/json" \
  https://fhir.allegiancemd.io/R4/.well-known/smart-configuration | python -m json.tool

🛡️ Authentication, Authorization & Scopes

User authentication and scope configuration

User Authentication

For authorization code flows, end users authenticate using credentials provided by the PHI Provider. Organizations may re-use existing patient portal or EHR credentials, mapping the authenticated user to a unique patient portal or EHR account.

Scopes

Your application requests scopes during the OAuth authorization step. Supported scopes depend on Provider configuration and the access context (patient, workforce, or system level).

Offline Access

Apps that can securely store refresh tokens may request the offline_access scope to receive a long-lived refresh token, subject to user and Provider approval.

📖 API Documentation & Reference

Interactive tools and human-readable documentation

📜 Terms of Use

Developer agreement and usage terms

All developers must agree to the Application Access Developer Agreement prior to integration.

🎧 Support & Change Management

Getting help and staying up to date

Support & Onboarding

Start with the PHI Provider that granted your application access. The Provider administers your registration and user provisioning and can coordinate escalation to AllegianceMD as needed.

Change Management

Integrations should be designed to tolerate routine platform updates. Where changes affect API compatibility, monitor the published documentation and the /metadata CapabilityStatement for current behavior and supported features.

🚀 Quick Start — Developer Checklist

Get up and running in 5 steps

📡 Appendix A.1 — CapabilityStatement

Live, authoritative conformance declaration for the FHIR R4 server

Key Fields

List Supported Resource Types

# Retrieve and list all supported resource types
curl -s -H "Accept: application/fhir+json" \
  https://fhir.allegiancemd.io/R4/metadata \
  | python - <<'PY'
import json, sys
cs = json.load(sys.stdin)
types = set()
for rest in cs.get("rest", []):
    for r in rest.get("resource", []):
        t = r.get("type")
        if t: types.add(t)
for t in sorted(types): print(t)
PY

List Interactions Per Resource

# List interactions available for each resource type
curl -s -H "Accept: application/fhir+json" \
  https://fhir.allegiancemd.io/R4/metadata \
  | python - <<'PY'
import json, sys
cs = json.load(sys.stdin)
for rest in cs.get("rest", []):
    for r in rest.get("resource", []):
        rtype = r.get("type")
        interactions = [i.get("code") for i in r.get("interaction", []) if i.get("code")]
        if rtype:
            print(f"{rtype}: {', '.join(interactions)}")
PY

🔍 Appendix A.2 — SMART Discovery

Programmatic discovery of SMART-on-FHIR endpoints and capabilities

Typical Response Fields

# Pretty-print SMART configuration
curl -s -H "Accept: application/json" \
  https://fhir.allegiancemd.io/R4/.well-known/smart-configuration | python -m json.tool

🔐 Appendix A.3 — PKCE Requirement

Proof Key for Code Exchange for authorization code flows

If your application uses the authorization code flow, PKCE is required. Use the S256 code challenge method as defined by RFC 7636.

⚠️ Appendix A.4 — Error Handling

HTTP status codes and OperationOutcome responses

Errors are returned as standard HTTP status codes. For FHIR-level processing errors, the server may return an OperationOutcome resource with details in the issue[] element.

Always Log

⏱️ Appendix A.5 — Rate Limiting / Fair Use

Handling throttling and retry behavior

If rate limits are applied, clients should honor server responses and implement exponential backoff for retryable failures. Providers may apply additional contractual or operational controls consistent with the published Terms of Use.

💻 Appendix B — Request Examples

Minimum request examples for FHIR + OAuth

FHIR Request (Bearer Token Required)

GET https://fhir.allegiancemd.io/R4/Patient/{id}
Authorization: Bearer <access_token>
Accept: application/fhir+json

CapabilityStatement Request

GET https://fhir.allegiancemd.io/R4/metadata
Accept: application/fhir+json

SMART Config Request

GET https://fhir.allegiancemd.io/R4/.well-known/smart-configuration
Accept: application/json