Skills Development OpenEvidence Security Best Practices Guide

OpenEvidence Security Best Practices Guide

v20260423
openevidence-security-basics
This guide provides essential security protocols and coding best practices for integrating with OpenEvidence, a platform processing Protected Health Information (PHI). It covers mandatory topics such as HIPAA compliance, API key management, webhook signature verification, input validation, and data redaction, ensuring all interactions are secure and audit-compliant.
Get Skill
120 downloads
Overview

OpenEvidence Security Basics

Overview

OpenEvidence provides AI-powered clinical evidence synthesis that processes protected health information (PHI), patient queries, and medical literature references. Integrations must comply with HIPAA requirements for PHI handling, audit logging, and access controls. A breach exposes patient health questions, clinical recommendations, and potentially identifiable medical conditions. Every API interaction must be treated as a HIPAA-regulated transaction.

API Key Management

function createOpenEvidenceClient(): { apiKey: string; baseUrl: string } {
  const apiKey = process.env.OPENEVIDENCE_API_KEY;
  if (!apiKey) {
    throw new Error("Missing OPENEVIDENCE_API_KEY — store in HIPAA-compliant secrets manager");
  }
  // PHI-adjacent access — enforce audit logging on every request
  console.log("OpenEvidence client initialized (key suffix:", apiKey.slice(-4), ")");
  return { apiKey, baseUrl: "https://api.openevidence.com/v1" };
}

Webhook Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyOpenEvidenceWebhook(req: Request, res: Response, next: NextFunction): void {
  const signature = req.headers["x-openevidence-signature"] as string;
  const secret = process.env.OPENEVIDENCE_WEBHOOK_SECRET!;
  const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    res.status(401).send("Invalid signature");
    return;
  }
  next();
}

Input Validation

import { z } from "zod";

const ClinicalQuerySchema = z.object({
  query_id: z.string().uuid(),
  clinical_question: z.string().min(10).max(2000),
  specialty: z.enum(["oncology", "cardiology", "neurology", "general", "pediatrics", "emergency"]).optional(),
  evidence_level: z.enum(["systematic_review", "rct", "cohort", "case_report", "expert_opinion"]).optional(),
  include_guidelines: z.boolean().default(true),
});

function validateClinicalQuery(data: unknown) {
  return ClinicalQuerySchema.parse(data);
}

Data Protection

const OPENEVIDENCE_PHI_FIELDS = ["patient_name", "date_of_birth", "mrn", "clinical_question", "diagnosis", "medication_list"];

function redactOpenEvidenceLog(record: Record<string, unknown>): Record<string, unknown> {
  const redacted = { ...record };
  for (const field of OPENEVIDENCE_PHI_FIELDS) {
    if (field in redacted) redacted[field] = "[REDACTED_PHI]";
  }
  return redacted;
}

Security Checklist

  • [ ] API keys stored in HIPAA-compliant secrets manager
  • [ ] Separate keys per environment (dev/staging/prod)
  • [ ] Key rotation scheduled quarterly
  • [ ] HIPAA audit logging enabled on every API call
  • [ ] PHI never logged in application logs (field-level redaction)
  • [ ] BAA (Business Associate Agreement) on file with OpenEvidence
  • [ ] Clinical query data encrypted at rest and in transit (TLS 1.2+)
  • [ ] Access controls enforce minimum necessary PHI exposure

Error Handling

VulnerabilityRiskMitigation
Leaked API keyUnauthorized access to clinical evidence queriesHIPAA-compliant secrets manager + rotation
PHI in application logsHIPAA violation and patient data exposureMandatory PHI field redaction
Missing BAARegulatory non-compliance penaltyBAA signed before integration goes live
Unencrypted clinical dataPHI breach during transit or storageTLS 1.2+ in transit, AES-256 at rest
Missing audit trailHIPAA audit failureImmutable audit logs for all API interactions

Resources

Next Steps

See openevidence-prod-checklist.

Info
Category Development
Name openevidence-security-basics
Version v20260423
Size 3.35KB
Updated At 2026-04-28
Language