Tenant API

Who this page is for: a developer or IT integrator working against a Refera tenant - everything the API accepts, returns and refuses.

Available on all plansthe same API surface on every tier

A tenant owner can require a verified second factor before any human session may write.

The tenant API is a small, boring HTTP surface: JSON in, JSON out, bearer tokens, no SDK required. It exposes exactly what the console shows - arrival-ordered referrals, their sealed event history, the admin process-state transitions - and nothing else. The compliance walls are enforced in code, not in documentation: requests that try to cross them are refused with a 400 that says why.

Authentication

Every route under /api requires a bearer credential:

Authorization: Bearer <token>

The same server supports two credential lanes:

• A local test tenant token - private fixtures only. The licensed AWS runtime starts with an empty static tenant directory and accepts no sample-machine bearer.
• A human session bearer issued by /api/auth/*. Live access accepts a user-verified WebAuthn passkey, or single-use email proof combined with a current TOTP code. See Signing in for the full flow.

Activation automatically refuses email-only and TOTP-only sessions. Recovery proof is scoped to factor replacement and never authorises a referral API call. A refused session receives a 403 carrying the available upgrade routes.

Endpoints

Method and path	What it does
GET /health	No auth. Service posture: store id, sealer id, the compliance line.
GET /api/referrals	Arrival-ordered referral list for your tenant, without event bodies. Optional ?state= filter.
GET /api/referrals/:id	One referral with its full sealed event history.
GET /api/referrals/:id/source	Exact archived inbound envelope, scoped by the authenticated tenant and verified referral source evidence. Fails closed until the complete source retrieval lifecycle is proven and activated.
POST /api/referrals/:id/events	Append one admin process-state transition. The chain is verified before the append and the new event is sealed through the same core module the console uses.
GET /api/referrals/:id/verify	Independent seal-chain re-verification of that referral’s history.
GET /api/settings/export	Owner/Admin sanitized tenant JSON attachment. Fails closed unless the keyed tenant export-audit append succeeds first.
GET /api/settings/evidence-export	Human Owner/Admin ZIP64 package with exact originals and SHA-256 manifest; no HMAC key. Fails closed unless the keyed tenant export-audit append succeeds first.
/api/auth/*	Account email bootstrap, session introspection/logout, passkey registration and passkey sign-in. Patient-data API access accepts WebAuthn sessions only. Signing in documents it.

Listing referrals

curl -s -H 'Authorization: Bearer <token>' \
  'https://<your-tenant-endpoint>/api/referrals?state=waiting_info'

The response is explicit about its ordering contract:

{
  "tenant": "riverbend",
  "order": "arrival (receivedAt, id) - never urgency",
  "count": 12,
  "items": [ ... ]
}

Listings are arrival-ordered, always - receivedAt then id. The state filter narrows the list; it never re-orders it. Valid states are the console’s own process vocabulary: new, in_review, waiting_info, ready_for_pms, entered, declined, unmatched - anything else is a 400 that lists the valid set.

Recording a transition

curl -s -X POST -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"type":"info_requested","actor":"[email protected]","note":"Medicare number missing - chase sent"}' \
  'https://<your-tenant-endpoint>/api/referrals/REF_E040/events'

Exactly five event types are accepted - the staff-actor vocabulary of the process model, each mapping to one resulting state:

Event type	Resulting state
review_started	in_review
info_requested	waiting_info
marked_ready	ready_for_pms
entered_in_pms	entered
declined	declined

Three fields are allowed on the body: type, note, actor. The rules around them:

• Unknown fields are refused with a 400 naming the field.
• The compliance wall is enforced at the field level: any key whose name matches the urgency, priority, acuity, severity or clinical register is refused outright. The refusal quotes the posture line verbatim: Refera tracks referral admin only. It does not triage patients.
• Settled referrals stay settled. A referral in entered or declined answers 409 to further transitions.
• A broken chain is never laundered. The event history is re-verified before every append; if verification fails, the API answers 409 with the break position and refuses to write.

A successful append returns 201 with the event as sealed and the new chain head:

{ "id": "REF_E040", "status": "waiting_info", "event": { ... }, "chainHead": "#4f2c9a1d" }

Pipeline events - received, extracted, match_failed, flagged_duplicate - are ingest-time facts recorded by capture itself and cannot be issued through this API.

Verifying a chain

curl -s -H 'Authorization: Bearer <token>' \
  'https://<your-tenant-endpoint>/api/referrals/REF_E011/verify'

Verification recomputes every seal server-side through the core seal module and reports either the intact chain head or the exact break position and reason. It is the same walk the console’s verify panel performs and the same one you can re-implement from the export format alone - see Verify your history.

The storage adapter

The API only ever talks to a storage adapter. The licensed portal uses the encrypted, tenant-partitioned DynamoDB store in ap-southeast-2; local tests and the private release smoke use a JSON adapter seeded with patient-free fixtures. The adapter boundary keeps the HTTP contract identical without presenting fixture storage as production architecture.

Every behaviour on this page is asserted over the wire by the automated server suite on every merge: endpoint coverage, the field-level refusals, settled-state 409s and tamper detection on the verify route.

Related

• Signing in - passkeys, email-plus-authenticator access, recovery and session controls.
• Verify your history - the seal walk in full.
• Process states and chips - the state vocabulary as the console renders it.