API Reference

Security Best Practices

Health Gorilla requires all API integrations to follow strict security protocols to protect patient data and maintain compliance with healthcare standards such as HIPAA and TEFCA.

This page outlines best practices for securely managing OAuth credentials, API access, and sensitive data within your application.

Enforce HTTPS

  • All OAuth and FHIR API endpoints require TLS 1.2 or higher.
  • Plain HTTP requests are rejected.
  • Never disable certificate validation in production environments.

Minimize Scope Usage

  • Request only the scopes you need for the specific workflow.
  • Avoid using user/. unless your application genuinely requires full access.
  • Use granular scopes like patient/*.read or user/Observation.read when possible.

Protect Client Secrets

  • Treat your client_secret like a password:
    • Never expose it in frontend or mobile code.
    • Store it securely using an encrypted secret manager or environment variable.
  • Rotate client secrets periodically.
  • Immediately revoke and reissue credentials if compromise is suspected.

Token Handling

  • Never log or cache access tokens or refresh tokens in plaintext.
  • Access tokens should only be stored temporarily and securely (e.g., in memory).
  • Refresh tokens should be encrypted at rest and never exposed to users.
  • Implement token revocation on logout or system deactivation.

Validate Webhooks and Callbacks

  • Verify webhook signatures (if provided) to ensure authenticity.
  • Always validate incoming request payloads against expected formats.
  • Require TLS for all callback URLs (redirect URIs and webhooks).

Monitor and Rate Limit Usage

  • Monitor access patterns to detect abuse, credential leaks, or unintended loops.
  • Use rate limiting to prevent brute force attacks and protect backend resources.
  • Use logging and audit trails to track API usage by client and user.

Align with Your Organization’s Compliance Policies

  • Perform regular vulnerability scans and security reviews.
  • Ensure audit logging is enabled and retained as required.
  • Align your data retention policies with healthcare compliance frameworks.

Following these best practices helps ensure secure, compliant, and stable integrations with Health Gorilla’s platform.