Your first $match call

1. Register

Visit /auth/signup/ and create an account with your work email. The portal sends a verification email immediately.

Register or sign in if you already have an account

2. Verify your email

Open the verification email and click the link. You’ll be redirected back to the portal in a verified state — this is enforced by the portal’s allauth configuration (ACCOUNT_EMAIL_VERIFICATION = "mandatory").

If the email doesn’t arrive within a few minutes: check spam, then contact support@onyxhealth.io.

3. Request Test access

From your dashboard, click “Request Test access”. The portal calls MORTAL’s admin API, which generates a Subscriber ID + one Test credential, and immediately redirects you to a one-shot reveal page.

The client_secret is shown exactly once. Copy it to your password manager or a secret store before navigating away — the portal does not retain it.

4. Authenticate

MORTAL uses OAuth2 client_credentials. Exchange your credentials for a bearer token:

curl -X POST \
  https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token \
  -d "client_id=<your_client_id>" \
  -d "client_secret=<your_client_secret>" \
  -d "grant_type=client_credentials" \
  -d "scope=api://onyx-mortal/.default"

The response contains access_token (valid 60 min). Cache it in-process; re-request when it expires.

5. Call $match

Send a FHIR Patient resource describing the person you want to match against SSA / state mortality records. The full request and response shape is documented in the API reference; here’s a minimal example:

curl -X POST \
  https://api.mortal.onyxos.io/Patient/\$match \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-MORTAL-Subscriber-Id: <your_subscriber_id>" \
  -H "Content-Type: application/fhir+json" \
  -d @match-request.json

Use synthetic data (e.g. Synthea, or hand-crafted test records). Do not send real PHI to the Test environment.

6. Request Production access

When your integration is ready, submit a short business justification from your dashboard. A Veritas administrator reviews and approves; you’ll receive an email with a fresh one-shot reveal URL for the Production credential.

Production credentials are issued on a separate Credential row with environment = "prod". Your Subscriber ID stays the same.