Go-live checklist

Before you flip from sandbox to live, walk this list. In sandbox every key resolves to synthetic patients, so mistakes are cheap. In live, an order is a real shipment of a compounded drug — so the goal here is that nothing surprises you the first time a real patient flows through.

Swap keys#

• Replace every nk_sandbox_… key with a nk_live_… key. Live keys require an active agreement — see Authentication.
• Confirm your app reads the key from configuration (an env var, a secret manager), not a hard-coded constant. Sandbox and live should differ only by which key is loaded.
• Verify the base URL and version are what you expect: https://api.neolife.health/v1.

Sandbox and live are fully isolated. A nk_sandbox_… key can never touch a real patient, and a nk_live_… key never resolves to synthetic data. There is no "test mode" flag to forget — the environment is the key.

Store and rotate keys#

• Keep keys server-side only. Never ship a key in a browser bundle, a mobile app, or client-side config — a live key can submit real orders.
• Store keys in a secret manager or your platform's environment config, not in source control.
• Have a rotation path ready: if a key is ever exposed, create a new key, deploy it, then revoke the old one. Revocation is immediate.
• Scope keys to what each service needs, and use separate keys per service so you can revoke one without taking everything down.

Always send an Idempotency-Key#

• Send an Idempotency-Key (a UUID) on every mutation — POST, PATCH, PUT. This is what makes a retried request safe on a fulfillment rail.
• Derive keys deterministically from the logical operation (for example a UUIDv5 of submit:ord_123), so a retry replays instead of re-shipping.
• On any retry — network drop, timeout, 429 — reuse the same key. A different key on a retry looks like a brand-new request.

The SDKs and MCP server generate stable keys for you. Full rules in Idempotency.

Verify and dedupe webhooks#

• Verify the signature on every incoming webhook before trusting it — reject anything that doesn't validate. See Webhooks for the exact header and verification steps.
• Respond 2xx fast, then process asynchronously. Slow handlers get retried.
• Deduplicate by event id. Webhooks are delivered at-least-once, so the same event can arrive more than once — treat delivery as idempotent and no-op on an id you've already seen.
• Have a reconciliation fallback: if a delivery is missed, pull the durable event log rather than assuming a webhook arrived.

Handle rate limits and backoff#

• Treat 429 as expected under load, not an error. Honor the backoff and retry.
• Retry 429s (and transient 5xxs) with exponential backoff and jitter — and always with the same Idempotency-Key so the retry is safe.
• Don't retry 4xxs other than 429. A 409, 422, or 403 means the request needs to change, not to be resent as-is. See the error reference.

Keep PHI in scope#

• Confirm your webhook endpoint stays PHI-free. Events carry ids and status only, so your callback surface stays out of PHI scope — keep it that way. See the PHI boundary.
• Any code that reads patient detail over an authenticated GET runs on in-scope infrastructure. Draw the line so PHI never lands on the same box as your public webhook receiver.
• Don't log request/response bodies from patient-detail GETs into general-purpose logging.
• Never put patient data in an Idempotency-Key, a URL, or anywhere it can leak — keys are UUIDs by design for exactly this reason.

Subscribe to the events you need#

• Register your production webhook endpoint and subscribe only to the event types you act on.
• Make sure every order state you care about — approval, submission, fulfillment status — is covered by either a webhook subscription or a scheduled pull of the event log.
• Confirm a licensed provider approves every clinical order in your live flow. The API refuses to submit an unapproved order, so wire your UX to that gate rather than around it.

Final smoke test#

• Run one real end-to-end order in live with a key you can revoke, and watch it flow through approval, submission, and fulfillment events.
• Confirm your dashboards and alerts fire on the live event stream, not just sandbox.
• Keep the X-Request-Id from responses in your logs — it's what support needs to trace anything.