Production and sandbox base URLs are issued during onboarding. All requests must use HTTPS with TLS 1.2 or higher. Paths are rooted at /api/... relative to your assigned host.

Curably supports two authentication modes:

• Bearer token (staff context) — Supabase session JWT for provider, pharmacy, HMO, and admin workspace calls. Obtained after staff sign-in with MFA where required.
• Organization API keys — Server-to-server tokens with least-privilege scopes per module (records, verifications, webhooks). Managed under Admin → Integrations.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Pharmacy-specific endpoints are documented in Pharmacy API. EHR sync endpoints are covered in EHR integration.

Register webhook URLs via POST /api/orgs/webhooks with { org_id, url }. Curably generates a per-endpoint secret used to sign deliveries.

{
  "event": "consent.created",
  "org_id": "uuid",
  "patient_id": "uuid",
  "subject_cura_id": "CURA-XXXX",
  "scopes": ["records.read", "medications.read"],
  "timestamp": "2026-06-10T14:32:00Z"
}

Supported events:

• consent.created — beneficiary granted scoped access
• consent.revoked — access withdrawn
• visit.started — encounter opened at facility
• visit.closed — encounter closed with billing context
• verification.flagged — identity or fraud signal raised
• webhook.created — audit event on endpoint registration

Failed deliveries retry with exponential backoff (1s, 2s, 4s, 8s — max 5 attempts). Your endpoint should return 2xx within 10 seconds.

Webhook deliveries include X-Cura-Signature: sha256=<hex> computed as HMAC-SHA256 of the raw request body using your endpoint secret.

const crypto = require("crypto");

function verifyWebhook(req, secret) {
  const sig = req.headers["x-cura-signature"] || "";
  const raw = req.rawBody || JSON.stringify(req.body);
  const h = crypto
    .createHmac("sha256", secret)
    .update(raw, "utf8")
    .digest("hex");
  return sig === "sha256=" + h;
}

• Use Idempotency-Key on POST requests to prevent duplicate writes during retries
• On 429 Too Many Requests, honor the Retry-After header
• Default sandbox limit: 120 requests/minute per org; production limits scale with contract tier