API keys

Integrations talk to Xenrad with a site-scoped API key. The same kind of key works for FHIR, HL7 over HTTP, and MPPS. A key belongs to one site and an owning user. Callers send it in the X-API-Key header on those HTTPS hosts. MLLP is different. It uses the integration client’s IP and MSH rules, not a header key.

Use the hosts shown in Endpoints reference for each surface.

Prerequisites

You need admin access to the site you are integrating, and permission to create and manage API keys for that site. If you cannot open the API keys screen, stop and ask an admin rather than guessing credentials from another environment.

Create a key

Open the site in Horizon (https://app.stg.xenrad.io) and go to API keys. Create a key with a clear name so the next person knows what system it serves. If the form asks for an owning user, pick the one your policy requires. When the key is revealed, store it immediately. It is only shown once.

Use the key

Send the key on every HTTPS integration request:

X-API-Key: <api_key>

For example, a FHIR metadata call for this environment:

curl -sS \
  -H "X-API-Key: $XENRAD_API_KEY" \
  -H "Accept: application/fhir+json" \
  "https://fhir.stg.xenrad.io/fhir/metadata"

HL7 over HTTP and MPPS use the same header on their own hosts. Paths differ by surface. See the endpoints chapter.

Revoke a key

Revoke keys from the same site API keys screen. Revoked keys stop authenticating immediately. The record usually stays visible so audit trails still make sense.

Habits that keep you out of trouble

Keep keys in a secret manager, not chat, tickets, or source control. Rotate by creating a new key, deploying it to the integration, then revoking the old one. Prefer separate keys per facility system so you can revoke one bridge without killing every other feed.

When a call starts failing with an auth error after a quiet period, assume rotation or revocation first, not a code bug in your client.