OpenEvidence Security Basics

Table of Contents

• Overview
• Prerequisites
• Instructions
• Output
• Error Handling
• Examples
• Resources

Overview

Security best practices for OpenEvidence integrations handling Protected Health Information (PHI). Covers credential management, PHI sanitization, HIPAA audit logging, webhook verification, and data retention compliance.

Prerequisites

• OpenEvidence SDK installed
• Understanding of HIPAA requirements
• Signed Business Associate Agreement (BAA)
• Access to organization security policies

OpenEvidence Security Certifications

• SOC 2 Type II certified
• HIPAA compliant with BAA
• AES-256 encryption at rest
• TLS 1.2+ encryption in transit

Security Checklist

• API keys in secret manager (not env vars in production)
• BAA signed with OpenEvidence
• PHI sanitization before all queries
• HIPAA audit logging on all access
• Webhook signatures verified
• TLS 1.2+ enforced
• Different keys for dev/staging/prod
• Key rotation schedule established
• Data retention policy implemented

Instructions

Step 1: Secure Credential Management

Use .env locally (gitignored), GCP Secret Manager or AWS Secrets Manager in production. Never hardcode credentials.

Step 2: Implement PHI Sanitization

Remove names, dates, MRNs, SSNs from queries before sending to OpenEvidence. Map patient demographics to age ranges and condition categories instead of specific identifiers.

Step 3: Enable HIPAA Audit Logging

Log all clinical queries and DeepConsult requests with userId, userRole, resourceId, ipAddress, success status. Never log actual query content or responses (may contain PHI).

Step 4: Verify Webhook Signatures

Parse t=timestamp,v1=signature header format. Compute HMAC-SHA256 with timing-safe comparison. Reject timestamps older than 5 minutes for replay protection.

Step 5: Configure Data Retention

• Audit logs: 6 years (2190 days) -- HIPAA minimum
• Query results: Do not store (re-query as needed)
• DeepConsult reports: 1 year
• Run daily cleanup job to enforce policies

Output

• Secure credential management (GCP/AWS Secret Manager)
• PHI sanitization layer with pattern detection
• HIPAA-compliant audit logging
• Webhook signature verification with replay protection
• Data retention compliance with automated cleanup

Error Handling

Examples

Secure Query Flow

const sanitized = sanitizeQueryForOpenEvidence(question, patientContext);
const response = await client.query({ question: sanitized.question, context: sanitized.context });
await auditLogger.logClinicalQuery(user.id, user.role, response.id, true, request);

See detailed implementation for advanced patterns.

Resources

• OpenEvidence Security
• HIPAA Security Rule
• NIST Cybersecurity Framework