Endpoints reference

This page shows the integration endpoints for your deployment with their current resolved IP addresses. If an endpoint shows not configured, contact your administrator.

Each card shows the env var name your administrator sets to configure that endpoint. If you're setting up your own environment file, use these names.

What each endpoint is for

OAuth2 / SMART — INTEGRATION_OAUTH_PUBLIC_BASE_URL

You must obtain an access token here before calling any other integration endpoint.

• GET /.well-known/smart-configuration — discovery document with the live token_endpoint, supported scopes, and auth methods.
• POST /oauth2/token — exchange a signed client assertion for a Bearer access token.

Always read token_endpoint from the live discovery document—don't hard-code the path, as reverse proxies may rewrite it.

→ OAuth2, API keys, and client assertions

FHIR R4 — INTEGRATION_FHIR_PUBLIC_BASE_URL

The FHIR service is on its own base URL, separate from the web application.

• GET /fhir/metadata — capability statement confirming supported resource types.
• GET, POST, PUT on /fhir/{ResourceType}/... — patient data, observations, reports, and more.

Authenticate with a Bearer token whose aud claim is xenrad-fhir.

→ FHIR integration

HL7 HTTP — INTEGRATION_HL7_HTTP_PUBLIC_BASE_URL

For teams that prefer HTTPS over a persistent TCP connection.

• POST /hl7/messages — send an HL7 v2.5.1 message with Authorization: Bearer.

Token audience must be xenrad-hl7-http.

→ HL7 integration

HL7 MTTP (TCP / MLLP) — INTEGRATION_HL7_MTTP_DOMAIN · INTEGRATION_HL7_MTTP_PORT

For hospital interface engines that speak HL7 over a persistent TCP connection. Your engine connects to the domain and port above; messages use standard MLLP framing.

IP allow-listing applies on your API key—see HL7 integration for setup.

→ HL7 integration

API Documentation — INTEGRATION_DOCS_URL

The interactive API reference for this deployment. Browse endpoints, try requests in-browser, and inspect request/response schemas.

Building a full URL

Quick connectivity checks

Verify SMART discovery

curl -sS "${INTEGRATION_OAUTH_PUBLIC_BASE_URL}/.well-known/smart-configuration" | jq .

Expected response:

{
  "issuer": "https://auth.example.com",
  "token_endpoint": "https://auth.example.com/oauth2/token",
  "token_endpoint_auth_methods_supported": ["private_key_jwt"],
  "grant_types_supported": ["client_credentials"]
}

Get an access token

curl -sS -X POST "${INTEGRATION_OAUTH_PUBLIC_BASE_URL}/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  --data-urlencode "client_assertion=YOUR_JWT" \
  --data-urlencode "scope=system/Patient.read" \
  --data-urlencode "audience=xenrad-fhir"

Expected response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "system/Patient.read"
}

Search FHIR patients

curl -sS "${INTEGRATION_FHIR_PUBLIC_BASE_URL}/fhir/Patient?name=smith" \
  -H "Accept: application/fhir+json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Send an HL7 message over HTTP

curl -sS -X POST "${INTEGRATION_HL7_HTTP_PUBLIC_BASE_URL}/hl7/messages" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary $'MSH|^~\\&|APP|FAC|XEN|FAC|20240101120000||ADT^A08|1|P|2.5.1\rPID|1||ID1||Doe^John||19800101|M\r'

Check MLLP port reachability

nc -zv "${INTEGRATION_HL7_MTTP_DOMAIN}" "${INTEGRATION_HL7_MTTP_PORT}"

Related

• OAuth2, API keys, and client assertions
• FHIR integration
• HL7 integration