API keys

Xenrad integrations use site-scoped API keys for FHIR, HL7 over HTTP, and MPPS. A key belongs to a site and an owning user. Callers send it in the X-API-Key header on those HTTPS hosts (not on MLLP, which uses integration-client IP and MSH rules instead).

Use the host shown in Endpoints reference for each surface.

Prerequisites

Admin access in the Xenrad web app to the site you are integrating.
Permission to create and manage API keys for that site.

Create an API key

Open the site in the Xenrad app.
Go to API keys.
Create a key with a clear name and, if needed, select the user it should belong to.
Store the revealed key immediately. It is only shown once.

Use the key

Send the key as:

X-API-Key: <api_key>

Examples (hosts come from this documentation site when your team configures the build):

Replace each host below with the HTTPS bases your organization uses for Xenrad (FHIR, HL7 HTTP, and MPPS are separate URLs).

# FHIR (https://fhir.integrations.xenrad.io)
curl -sS "https://fhir.integrations.xenrad.io/fhir/Patient?name=smith" \
  -H "Accept: application/fhir+json" \
  -H "X-API-Key: YOUR_XENRAD_API_KEY"

# HL7 HTTP (https://hl7.integrations.xenrad.io)
curl -sS -X POST "https://hl7.integrations.xenrad.io/v2/ingest" \
  -H "X-API-Key: YOUR_XENRAD_API_KEY" \
  -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'

# MPPS (https://mpps.example.com)
curl -sS -X POST "https://mpps.example.com/ingest" \
  -H "X-API-Key: YOUR_XENRAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sop_instance_uid":"1.2.3.4.5","study_uid":"1.2.3.4.5.6","status":"IN PROGRESS"}'

Revoke a key

Revoke keys from the same site API keys screen. Revoked keys stop authenticating immediately and remain visible for audit context.

Operational tips

Keep keys in a secret manager, not source control or shared documents.
Rotate keys by creating a new key, deploying it to the integration, then revoking the old key.
Use separate keys per facility system where audit and revocation boundaries matter.