FastAPI Health Data Consent — Category Checks, Time-Bound Grants, and Revocation

Short answer: treat health data consent as a time-bound, category-specific grant that is checked on every protected read, and make revocation invalidate that grant before cached or queued work can use it. A device-fingerprint risk score can justify stronger authentication for a logistics worker, but it cannot create consent or widen an existing grant. That separation is the important design decision.

The concrete flow is small enough to explain plainly. A driver signs in to a logistics health application, the authentication layer evaluates the device signal, and the consent layer independently asks whether this subject granted this actor access to this data category for this purpose at this moment. The handler returns data only after both decisions pass. Every decision emits an audit event, including denials.

How should health data consent category checks handle grants and revocation?

Make the check a pure policy decision over explicit inputs: subject, actor, category, purpose, current time, and grant version. Don't infer a category from a screen name or accept a broad boolean such as has_consent. A grant for an occupational vaccination record should not silently authorize access to a mental-health note, and a grant for care coordination should not be reused for an unrelated analytics job.

Authentication and consent answer different questions. Authentication establishes confidence about the actor. Consent establishes which use the subject allowed. OWASP recommends reauthentication after risk events and calls out device enrollment as a risk event; that supports a step-up decision when a device fingerprint changes. It still doesn't alter the consent record. The device score belongs beside the authorization input, not inside the grant.

I use four outcomes rather than a loose true/false result: allow, deny_no_grant, deny_expired, and deny_revoked. This is an implementation choice, not a universal standard, but it pays off in evals because a failing case identifies the broken boundary. Externally, all four denials can map to HTTP 403 without revealing which health category exists.

The catch is that category taxonomies age. If two teams can assign different categories to the same record, the policy engine cannot repair the disagreement. Put category assignment upstream, version the taxonomy, and require a migration decision when a category changes. I'm not sure any fixed taxonomy will fit every clinical and occupational workflow; the resolving evidence is a review of real record types and purposes with the people accountable for those uses.

A runnable FastAPI policy slice

This example keeps storage in memory so the consent boundary stays visible. It is runnable, but deliberately incomplete as an application: production persistence, identity verification, and encrypted transport sit outside this policy slice. The important part is the order of operations — authenticate, decide, fetch, audit — and the fact that data isn't fetched before authorization succeeds.

from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from enum import Enum
from typing import Literal

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel


app = FastAPI()


class Category(str, Enum):
    VACCINATION = "vaccination"
    FITNESS_FOR_DUTY = "fitness_for_duty"
    MENTAL_HEALTH = "mental_health"


@dataclass(frozen=True)
class Grant:
    grant_id: str
    subject_id: str
    actor_id: str
    category: Category
    purpose: str
    valid_until: datetime
    revoked_at: datetime | None
    version: int


class AccessRequest(BaseModel):
    subject_id: str
    actor_id: str
    category: Category
    purpose: str
    device_risk: Literal["low", "high"]
    reauthenticated: bool


GRANTS = {
    "grant-42": Grant(
        grant_id="grant-42",
        subject_id="driver-108",
        actor_id="clinic-7",
        category=Category.VACCINATION,
        purpose="occupational-care",
        valid_until=datetime.now(timezone.utc) + timedelta(days=30),
        revoked_at=None,
        version=3,
    )
}


def find_grant(request: AccessRequest) -> Grant | None:
    return next(
        (
            grant
            for grant in GRANTS.values()
            if grant.subject_id == request.subject_id
            and grant.actor_id == request.actor_id
            and grant.category == request.category
            and grant.purpose == request.purpose
        ),
        None,
    )


def decide(request: AccessRequest, now: datetime) -> tuple[bool, str]:
    if request.device_risk == "high" and not request.reauthenticated:
        return False, "reauthentication_required"

    grant = find_grant(request)
    if grant is None:
        return False, "deny_no_grant"
    if grant.revoked_at is not None and grant.revoked_at <= now:
        return False, "deny_revoked"
    if grant.valid_until <= now:
        return False, "deny_expired"
    return True, "allow"


@app.post("/records/read")
def read_record(request: AccessRequest) -> dict[str, str]:
    allowed, reason = decide(request, datetime.now(timezone.utc))
    audit(request, reason)
    if not allowed:
        raise HTTPException(status_code=403, detail="access_denied")

    return {"record_id": "record-9", "category": request.category.value}


def audit(request: AccessRequest, outcome: str) -> None:
    # Send structured metadata to an append-only audit sink; never log record data.
    print(
        {
            "subject_id": request.subject_id,
            "actor_id": request.actor_id,
            "category": request.category.value,
            "purpose": request.purpose,
            "outcome": outcome,
        }
    )

Run the policy as a normal Python service, then put most of the confidence in tests rather than prompts or prose. This is where notebook-to-prod habits help: turn each policy example into a fixture, keep expected decisions under version control, and rerun the suite whenever the category map or grant schema changes.

from datetime import datetime, timezone


def test_high_risk_device_requires_step_up() -> None:
    request = AccessRequest(
        subject_id="driver-108",
        actor_id="clinic-7",
        category=Category.VACCINATION,
        purpose="occupational-care",
        device_risk="high",
        reauthenticated=False,
    )
    assert decide(request, datetime.now(timezone.utc)) == (
        False,
        "reauthentication_required",
    )


def test_category_is_not_interchangeable() -> None:
    request = AccessRequest(
        subject_id="driver-108",
        actor_id="clinic-7",
        category=Category.MENTAL_HEALTH,
        purpose="occupational-care",
        device_risk="low",
        reauthenticated=False,
    )
    assert decide(request, datetime.now(timezone.utc)) == (
        False,
        "deny_no_grant",
    )

Two tests aren't enough. Add fixtures for an exact expiry boundary, revocation before and after the decision timestamp, actor mismatch, purpose mismatch, an unknown category, and concurrent reads during revocation. For AI-assisted development, keep generated cases in a review queue until they become deterministic fixtures. Token cost is then bounded to authoring or triage; the release gate itself remains fast, local, and repeatable.

Revocation is an ordering problem

Changing revoked_at is easy. Stopping already-dispatched work is harder.

Imagine the full race rather than only the database update. A worker checks consent at 10:00:00 and places an export job on a queue with allowed=true; the subject revokes at 10:00:01; one API node sees the new state immediately, while another node still holds the earlier decision in its local cache; then the export worker starts at 10:00:10. If the job contains only that boolean, it has no way to distinguish a current permission from a stale decision and will export data after revocation. Carry the grant ID and version instead. At execution time, reread the grant and reject the job if the version changed, the grant expired, or revoked_at is effective. Apply the same discipline to caches: a revocation event should invalidate entries keyed by grant ID, and a cache miss should retrieve current state rather than reuse an authorization result copied from another request. Now test each boundary independently: hold the queue until after revocation, delay invalidation on one node, and execute two jobs carrying different versions. This does more than test the happy path. It exposes which component owns freshness and turns an ambiguous promise such as "revocation is immediate" into observable ordering rules. Fail closed for access to the record itself.

Timing wins.

This creates a real trade-off. A synchronous grant read on every request gives the clearest revocation boundary but adds a dependency to the hot path. A short-lived cache reduces repeated reads but creates a measurable window that the product and compliance owners must accept explicitly. A versioned token can reduce lookups, yet it cannot know about later revocation without an online check or a bounded lifetime. There is no magic mode.

Batch and model pipelines deserve the same scrutiny. Don't place raw health text into an evaluation trace merely because the model call was authorized. Pass the minimum fields needed for the task, record the purpose and grant version with the run, and arrange deletion or exclusion behavior for revoked inputs before calling the workflow complete. In a prompt-cost-aware system, this also avoids paying to process fields that the decision never permitted the model to see.

Choosing the boundary, not a brand

The useful selection question is where the policy decision and grant state live. An embedded library is suitable when one service owns all reads and the team needs a small failure surface. A separate policy service fits multiple applications that share category and purpose rules, but it adds network latency and requires careful availability planning. A gateway check can reject obvious requests early, although it is not suitable as the only control when downstream jobs and internal reads bypass that gateway. Stick with application-level checks when the data access context exists only inside the application; choose a shared service when several independently deployed consumers must enforce the same revocation semantics.

Evaluate candidates with replayable cases, not feature matrices. Give each implementation the same set of grants and decision timestamps, then compare outcomes for category mismatch, expiry, revocation, step-up authentication, and queue execution. Measure decision latency at the percentile your application cares about, but don't let a fast allow response outweigh an incorrect allow. Correct denials come first.

Before production, walk one grant from creation through access, renewal, and revocation. Confirm that every protected read supplies actor, subject, category, and purpose; that high device risk requests reauthentication without changing consent; that audit records omit health content; that logs distinguish internal decision codes while clients receive a plain denial; and that queued work rechecks the current grant version. Finally, run the policy fixture suite against the exact artifact being deployed. If any consumer cannot participate in that walk, the boundary is still porous.

Sources

• https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html