Are you still letting engineers use a shared API key to query your patient‑data service?
In many teams the default pattern is a static credential baked into deployment scripts, a direct HTTP connection to the JSON endpoint, and a standing permission that never expires. The same key is used by dozens of services, and no one records which request returned which health record. When a breach occurs there is no audit trail, no way to block a rogue query, and no mechanism to hide protected health information (phi) from logs or downstream systems.
Even when organizations adopt modern identity providers and issue short‑lived tokens, the request still travels straight to the backend. The gateway that could inspect the payload is missing, so the token merely proves who can connect, not what they are allowed to see or write. Without a data‑path control point, phi can be exposed, edited, or logged unchecked.
That is the problem hoop.dev is built to solve. By inserting a Layer 7 gateway between the client and the JSON service, hoop.dev can enforce masking, approval, and audit policies on every request, while keeping the original credentials hidden from the caller.
Identifying phi in your JSON schema
Phi includes any individually identifiable health information, names, dates of birth, medical record numbers, lab results, and even derived values like risk scores. In a JSON document these fields appear as string, number, or enum properties. The challenge is that phi is often nested inside arrays or objects, making manual inspection error‑prone.
Typical red flags include:
- Properties named patientName, dob, mrn, or similar.
- Objects with a clinical or medical prefix.
- Arrays of observations that contain value fields paired with a unit field.
Because JSON schema can describe complex structures, a single top‑level definition may reference many subschemas. Relying on a single required list is insufficient; you need a systematic review of every properties block, including those pulled in via $ref.
Modeling phi safely with JSON schema features
JSON schema offers a few mechanisms that help you flag phi without changing the underlying data:
- Annotations: Use description or custom keywords like x‑phi to mark sensitive fields. Documentation tools can then surface these annotations for reviewers.
- Formats: Declare a format of date‑time for birth dates, or email for contact information. While not a security control by itself, it gives downstream processors a cue that the value is personal.
- Conditional schemas: The if/then/else construct can enforce stricter validation when a record is marked as type "patient", ensuring that phi fields are present and correctly typed.
These features do not encrypt or hide phi; they merely make the schema expressive enough for downstream enforcement points to act on.
Common pitfalls when handling phi in schemas
Even with careful annotation, teams often stumble over three recurring issues:
- Schema drift: As services evolve, new phi fields are added without updating the schema annotations, leaving gaps in detection.
- Over‑broad definitions: Using additionalProperties: true or a permissive anyOf can let unexpected phi slip through validation layers.
- Missing runtime enforcement: Validation at compile time is useful, but without a runtime guard the data can still be written to logs, caches, or external APIs.
Addressing these gaps requires a control point that sits on the data path, not just at the schema authoring stage.
Enforcing protection at the gateway
When a request to read or write JSON passes through a Layer 7 gateway, the gateway can inspect the payload, match it against the schema’s phi annotations, and apply a set of safeguards:
- Inline masking: Replace identified phi fields with redacted values before the response leaves the gateway.
- Command‑level approval: Route write operations that contain new phi to a human reviewer for explicit consent.
- Audit logging: Record the full request and response, including which fields were masked, to provide evidence for compliance audits.
- Just‑in‑time access: Grant temporary permission to a service account only for the duration of a single request that requires phi.
All of these outcomes are possible only because the gateway sits directly in the data path. Without that position, the application or agent could read or write phi unchecked.
Why hoop.dev fits the bill
hoop.dev is an open‑source Layer 7 gateway that can sit between any client, human, service account, or AI agent, and the target resource that stores JSON data. Because hoop.dev proxies the connection, it can apply the masking, approval, and audit controls described above without requiring code changes in the producer or consumer.
In practice, you would configure hoop.dev to:
- Validate incoming JSON against a schema that includes x‑phi annotations.
- Mask any phi fields in outbound responses, ensuring that downstream logs never contain raw health data.
- Require an approval step for write operations that introduce new phi, giving a compliance officer a chance to review.
- Record each session for replay, providing a complete audit trail that satisfies regulatory evidence requirements.
Because hoop.dev runs as a network‑resident agent, the credentials to the underlying datastore never leave the gateway. Engineers and automated jobs interact with hoop.dev using their normal client tools (curl, jq, or language‑specific SDKs), while hoop.dev enforces the policy in real time.
Getting started
To try this approach, start with the official getting‑started guide, which walks you through deploying hoop.dev with Docker Compose, registering a JSON‑based service, and adding phi annotations to your schema. The learn section provides deeper examples of masking and approval workflows.
For a hands‑on experience, follow the step‑by‑step instructions in the getting‑started documentation and explore the feature guides on the learn site. The repository contains all the configuration files you need to self‑host a secure gateway.
FAQ
Q: Does hoop.dev store phi itself?
A: No. The gateway holds only the credentials needed to reach the backend. All phi remains in the target system, and hoop.dev can mask it on the way out.
Q: Can I use hoop.dev with existing CI/CD pipelines?
A: Yes. Because hoop.dev works at the protocol level, you can point any pipeline step that talks to a JSON endpoint through the gateway without rewriting code.
Q: How does hoop.dev help with audit requirements?
A: Every request and response is recorded, including which fields were masked and who approved the operation. Those logs provide the evidence auditors look for under HIPAA and similar regulations.
Ready to protect your phi without rewriting your services? Explore the hoop.dev repository on GitHub and start building a compliant data pipeline today.
