Skip to content

Golden Age Hub — Route & Security Inventory

This document provides a comprehensive inventory of all Gateway API endpoints, detailing authentication requirements, permitted user roles, and multi-tenant data fencing enforcement mechanisms (Agency Fencing & Patient Fencing).

Security & Data Fencing Architecture

Golden Age Hub enforces a unified identity model and multi-tenant data fencing architecture via FastAPI security dependencies (backend/core/security/auth.py):

  1. Unified User Identity (UserIdentity):
  2. user_id: Unique identifier for the account (usr-xxx or pat-xxx).
  3. role: System role (admin, agency, caregiver, patient).
  4. agency_ids: List of multi-tenant agency UUIDs the user belongs to.

  5. assigned_patient_ids: List of patient UUIDs assigned to the user (caregiver/agency scope).

  6. Perimeter Authentication (get_current_user):

  7. Validates short-lived, signed JWT Bearer tokens issued by /api/v1/auth/login.
  8. Enforces Argon2id memory-hard password hashing and issuer verification (goldenage-auth-service).

  9. Unauthenticated requests are rejected at the gateway perimeter with 401 Unauthorized.

  10. Agency Fencing (enforce_agency_fencing):

  11. ADMIN: Global scope (bypasses agency boundary checks).

  12. AGENCY_ADMIN / CAREGIVER / PATIENT: Resource access is strictly restricted to target_agency_id IN (user.agency_ids). Cross-agency access yields 403 Forbidden.

  13. Patient Relationship Fencing (enforce_patient_fencing):

  14. ADMIN: Full administrative access.
  15. PATIENT: Self-access only (user.user_id == target_patient_id).

  16. CAREGIVER / AGENCY_ADMIN: Access restricted to assigned patient IDs (target_patient_id IN (user.assigned_patient_ids)). Unassigned access yields 403 Forbidden.

  17. Role-Based Guard (DataFenceGuard):

  18. Enforces explicit role permissions (allowed_roles) at the route level prior to request execution.

Route Inventory

1. Authentication & Identity Management

Endpoint Method Auth Required Permitted Roles Fencing & Scope Enforcement
/api/v1/auth/login POST ❌ Public All (Anonymous) Gated against production environment execution for demo accounts. Returns signed JWT token & user identity payload.
/api/v1/auth/me GET ✅ Bearer JWT admin, agency, caregiver, patient Injects get_current_user dependency. Returns token subject's identity, role, agency scopes, and patient assignments.

2. Main Dashboard & System Overview

Endpoint Method Auth Required Permitted Roles Fencing & Scope Enforcement
/api/v1/dashboard/stats GET ✅ Bearer JWT admin, agency, caregiver Protected by get_current_user. Aggregates active patients, devices, alerts, and pending exceptions within the user's agency scope.
/api/v1/dashboard/events-by-type GET ✅ Bearer JWT admin, agency, caregiver Protected by get_current_user. Aggregates event counts grouped by event type filtered by agency scope.
/api/v1/dashboard/events-by-time GET ✅ Bearer JWT admin, agency, caregiver Protected by get_current_user. Time-series distribution of incoming telemetry within agency scope.
/api/v1/dashboard/recent-events GET ✅ Bearer JWT admin, agency, caregiver Protected by get_current_user. Streams recent audit events scoped to assigned patients and agency tenants.

3. EVV & Visit Management (21st Century Cures Act)

Endpoint Method Auth Required Permitted Roles Fencing & Scope Enforcement
/api/v1/visits GET ✅ Bearer JWT admin, agency, caregiver, patient Injects get_current_user. Caregivers and patients are restricted to their assigned/own visit records.
/v1/visits GET ✅ Bearer JWT admin, agency, caregiver, patient Backward-compatible mount of visit query endpoint.
/api/v1/visits POST ✅ Bearer JWT admin, agency, caregiver Validates scheduled caregiver-patient visit creation. Enforces enforce_agency_fencing and enforce_patient_fencing.
/v1/visits POST ✅ Bearer JWT admin, agency, caregiver Backward-compatible visit creation endpoint.
/api/v1/visits/{visit_id} GET ✅ Bearer JWT admin, agency, caregiver, patient Enforces enforce_patient_fencing on target visit's patient_id.
/api/v1/visits/{visit_id}/resolve-exception POST ✅ Bearer JWT admin, agency Enforces DataFenceGuard([UserRole.ADMIN, UserRole.AGENCY_ADMIN]). Requires mandatory explanatory note (≥5 chars) and audit code.

4. Cryptographic Proof-of-Care Ledger (RFC 6962)

Endpoint Method Auth Required Permitted Roles Fencing & Scope Enforcement
/api/v1/proof-of-care/ledger-status GET ✅ Bearer JWT admin, agency, caregiver Injects get_current_user. Returns sealed Merkle tree height, root hash, and block state within agency scope.
/v1/proof-of-care/ledger-status GET ✅ Bearer JWT admin, agency, caregiver Direct mount point for ledger status.
/api/v1/proof-of-care/blocks GET ✅ Bearer JWT admin, agency, caregiver, patient Filtered by patient_id or device_id. Enforces enforce_patient_fencing when querying patient blocks.
/v1/proof-of-care/blocks GET ✅ Bearer JWT admin, agency, caregiver, patient Direct mount point for Merkle block list.
/api/v1/proof-of-care/blocks/{block_id} GET ✅ Bearer JWT admin, agency, caregiver, patient Returns specific Merkle block. Scope-validated against requesting identity.
/v1/proof-of-care/blocks/{block_id} GET ✅ Bearer JWT admin, agency, caregiver, patient Direct mount point for block retrieval.
/api/v1/proof-of-care/verify/{event_id} GET ✅ Bearer JWT admin, agency, caregiver, patient Generates audit inclusion proof (RFC 6962 audit path) for target event ID. Enforces patient/agency ownership.
/v1/proof-of-care/verify/{event_id} GET ✅ Bearer JWT admin, agency, caregiver, patient Direct mount point for Merkle verification.

5. Compliance & State Aggregator Exports

Endpoint Method Auth Required Permitted Roles Fencing & Scope Enforcement
/api/v1/exports/evv GET ✅ Bearer JWT admin, agency Exports Cures Act compliant visit log (JSON/CSV). Enforces enforce_agency_fencing on exports.
/v1/exports/evv GET ✅ Bearer JWT admin, agency Backward-compatible EVV export mount.
/api/v1/exports/rpm GET ✅ Bearer JWT admin, agency Exports Remote Patient Monitoring telemetry. Restricted to user's tenant agencies.
/api/v1/exports/audit-export POST ✅ Bearer JWT admin, agency Generates cryptographically verified HIPAA audit bundle with Merkle proofs.
/api/v1/exports/aggregator/{aggregator_name} POST ✅ Bearer JWT admin, agency Formats and transmits visit payloads to state aggregators (Sandata, HHAeXchange, Tellus). Enforces agency scope.

6. Event Ingestion & Processing

Endpoint Method Auth Required Permitted Roles Fencing & Scope Enforcement
/v1/events/ingest POST 🔐 Cryptographic (Device Key) Edge Devices / Hardware FOBs / App Device-Level Cryptographic Auth: Verifies Ed25519 payload signatures (verify_signature) and monotonically increasing sequence numbers (SequenceTracker). Replays return 409 Conflict.
/api/v1/events GET ✅ Bearer JWT admin, agency, caregiver Query events. Enforces agency scope filtering on returned event records.
/api/v1/events/{event_id} GET ✅ Bearer JWT admin, agency, caregiver, patient Retrieves single event detail. Enforces enforce_patient_fencing on event's associated patient ID.

7. Entity Management (Organizations, Caregivers, Patients, Devices)

Endpoint Method Auth Required Permitted Roles Fencing & Scope Enforcement
/api/v1/organizations GET ✅ Bearer JWT admin, agency Returns organization records. Non-admin users are restricted to agency_id IN (user.agency_ids).
/api/v1/organizations/{org_id} GET / PUT ✅ Bearer JWT admin, agency Enforces enforce_agency_fencing(user, org_id).
/api/v1/caregivers GET / POST ✅ Bearer JWT admin, agency Lists or provisions caregivers within the requesting user's agency tenant scope.
/api/v1/caregivers/{caregiver_id} GET ✅ Bearer JWT admin, agency, caregiver Enforces agency and self-caregiver access boundaries.
/api/v1/patients GET / POST ✅ Bearer JWT admin, agency, caregiver Queries/creates patient profiles. Results strictly filtered by assigned patient IDs for caregivers and agency IDs for agency admins.
/api/v1/patients/{patient_id} GET / PUT ✅ Bearer JWT admin, agency, caregiver, patient Enforces enforce_patient_fencing(user, patient_id).
/api/v1/devices GET / POST ✅ Bearer JWT admin, agency Lists/registers hardware telematics & software FOB devices scoped to user's agencies.

8. System & Operations Endpoints

Endpoint Method Auth Required Permitted Roles Fencing & Scope Enforcement
/health GET ❌ Public All System health check (pings database & Redis status, returns environment status).
/ws WebSocket ❌ Public / Connection Key Real-Time Clients WebSocket endpoint streaming system alerts and telemetry updates over Redis Pub/Sub.
/api/v1/policies GET / POST ✅ Bearer JWT admin Edge policy rules engine (alert_policy_rules.v1.json) management and feature flag versioning.

Scope Enforcement Decision Flow

                       ┌─────────────────────────────────────────────────────────┐
                       │                   Incoming Request                      │
                       └────────────────────────────┬────────────────────────────┘
                                                    │
                                         Is JWT Token Present?
                                        /                     \
                                      No                       Yes
                                      /                         \
                         HTTP 401 Unauthorized            Decode JWT Payload
                                                        (Extract UserIdentity)
                                                                 │
                                                       Is ADMIN Role Present?
                                                      /                      \
                                                    Yes                       No
                                                    /                          \
                                         Bypass Fencing Guards             Apply Scope Guards
                                            (Global Access)               ┌──────────┴──────────┐
                                                                          │                     │
                                                                 Agency Fencing       Patient Fencing
                                                                (agency_id IN        (patient_id IN
                                                               user.agency_ids)   assigned_patient_ids
                                                                                     OR self-access)

Documentation Maintenance & Governance Policy

To maintain architectural integrity and audit defense readiness:

  1. Synchronous Updates: Any pull request that creates, modifies, or deprecates an API endpoint MUST update this docs/route_inventory.md file alongside the code change.
  2. Mandatory Security Tests: New endpoints requiring authentication MUST include corresponding unit and adversarial cross-tenant test coverage in backend/tests/test_unified_auth_fencing.py.
  3. CI Gate: CI pipeline execution runs test_unified_auth_fencing.py on every PR; PR merge is strictly blocked if any security or data fencing test fails.