Provenance
Read the docs

Guide: clinician ordering + verified prescriber

An AI agent proposes a clinical order, such as a prescription, lab or referral, and a licensed human reviews the agent's reasoning and authorizes it before the order is placed, with a medico-legal record of who authorized exactly what, when, and with what credential. It's Authorize's exact shape (human intent bound to an agent action) plus two clinical specifics: the reviewer's reasoning surface and a verified prescriber identity.

Scope.

  • Provenance authorizes; your system places the order. We produce the authorization and the record, and deliver it to you through the order.authorized webhook.
  • Controlled substances. DEA EPCS signing requires NIST IAL2 proofing and an audited credential service provider, which is in progress. Until then, controlled orders can be reviewed and authorized for the record, and your system transmits them under its own authority.
  • Clinical judgment stays with the clinician. The agent supplies the reasoning, and Provenance binds and attests it. Drug-interaction and formulary checks run in your stack.

The one primitive: a verified prescriber identity

The verification tier is server-assigned from the credential sources that actually confirmed — a client-supplied tier is ignored (the same rule as for device hardware tiers).

| Tier | What confirms it | Source | | --- | --- | --- | | self_attested | a name on file, not yet verified | none | | npi_verified | a valid NPI whose name matches the CMS registry | NPPES (free public API) | | license_verified | an active state license with no disciplinary action | credential vendor | | dea_verified | a valid DEA registration | credential vendor |

A federal exclusion match (OIG LEIE / SAM.gov) sets excluded: true — a hard deny (prescriber_excluded) at order authorize, regardless of any tier.

Unconfigured sources. Each credential source is a separate provider. An unconfigured source leaves its tier unreachable. NPPES is built and free (no key). The license/DEA vendor and the SAM.gov exclusion key arrive later (a human track); until then tiers cap at npi_verified and the exclusion check is reported as unchecked.

curl $PROVENANCE_API/v1/prescribers \
  -H "Authorization: Bearer $PRV_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{ "full_name": "Jane Doe, MD", "npi": "1234567893" }'
# → { "prescriber_id": "presc_…", "tier": "npi_verified", "excluded": false,
#     "exclusion_checked": false, "evidence": [ { "source": "nppes", "npi_verified": true, … } ] }

The order flow

# 1. The agent proposes an order (payload hash-bound; reasoning context-bound).
curl $PROVENANCE_API/v1/orders \
  -H "Authorization: Bearer $PRV_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{ "prescriber_id": "presc_…", "order_type": "rx",
        "payload": { "drug": "amoxicillin", "dose": "500mg", "route": "PO", "quantity": 30, "frequency": "TID" },
        "reasoning": { "diagnosis": "strep pharyngitis", "differential": "viral URI" } }'
# → { "order_id": "ord_…", "status": "pending_review", "required_tier": "npi_verified", "approvals_needed": 1 }

# 2. The verified clinician authorizes with a biometric step-up.
curl $PROVENANCE_API/v1/orders/ord_…/authorize \
  -H "Authorization: Bearer $PRV_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{ "biometric_challenge": "…", "biometric_assertion": { … } }'
# → { "outcome": "authorized", "order": { "status": "authorized", "authorized_tier": "npi_verified", … } }

# 3. The signed authorization is delivered to YOUR system to place (order.authorized webhook).
#    Fetch the offline-verifiable receipt any time:
curl $PROVENANCE_API/v1/orders/ord_…/receipt -H "Authorization: Bearer $PRV_SECRET_KEY"
# → { "claims": { "order_id": "ord_…", "prescriber_tier": "npi_verified", "context_hash": "…" }, "receipt": "<ES256 JWS>" }

Clinical policy (declarative, not hardcoded)

Which orders need a higher tier and/or a co-sign is expressed in the policy engine, not hardcoded — a per-account, versioned clinical_order policy (edit it at PUT /v1/policy?domain=clinical_order). The built-in default:

Denials surface as prescriber_tier_insufficient, prescriber_excluded, or controlled_substance_cosign_required.

<provenance-order-review> — the review ceremony in your EHR

A mode="clinical-order" configuration of the <provenance-approve> embed. It renders the structured order (drug/dose in mono), the agent's stated reasoning (labeled agent-supplied), and the prescriber-tier badge — immutable trust chrome, a verifier verdict your theming can't style away — then biometric authorize / decline.

<script type="module" src="https://unpkg.com/@provenance/embed"></script>
<provenance-order-review
  base-url="https://api.provenance.io"
  publishable-key="prv_pub_…"
  embed-token="emb_…">
</provenance-order-review>
<script>
  document.querySelector("provenance-order-review")
    .addEventListener("pv:authorized", (e) => console.log("authorized", e.detail));
</script>

The ceremony never degrades in an embed: WebAuthn runs top-level, and the server enforces the exclusion / tier / co-sign gates regardless of the button. Confirm the outcome server-side (the order.authorized webhook or a read of the order) — never trust the event alone.

Pricing

An authorized order meters order_authorized ($0.25 — a high-value authorization); requirePlan(growth). Prescriber verification lookups are internal (vendor costs are ours) — no separate meter. NPPES and the exclusion check are free.