Authentication & Patient Security Specification

Module: API Security & Identity Management
Implementation Source: app/core/security.py

1. Authentication Mechanisms

The API supports two authentication methods for frontend applications and client services:

Method A: HTTP Bearer Token (Standard)

Send the access token in the Authorization request header:

Authorization: Bearer <ACCESS_TOKEN>

Method B: `X-API-Key` Custom Header

Send the API key in the custom X-API-Key header:

X-API-Key: <API_KEY>

2. Supported Access Tokens

1. Service Secret API Key

For service-to-service integration or administrative access:

Default Key: skyheal_secure_api_key_2026 (configurable via API_SECRET_KEY in server environment).

2. Patient Development / Testing Tokens

For patient-specific web or mobile client authentication:

Format: test_token_<PATIENT_ID>
Example: test_token_PAT-10023

When test_token_<PATIENT_ID> is passed, the backend automatically establishes the patient context with patient_id = "<PATIENT_ID>".

3. Patient Isolation & IDOR Protection Rules

The backend enforces strict Broken Object Level Authorization (IDOR) Protection:

When starting an onboarding session (/v1/onboarding/start or /v1/voice-onboarding/start), the patient.id provided in the JSON body is bound as the session owner (session.patient_id).
Subsequent requests to /message, /turn, /upload, or /complete verify that the caller's authenticated patient_id matches the session owner.

If Client B attempts to send a message to Client A's session, the server immediately returns HTTP 403 Forbidden:

{
  "detail": "Forbidden: You do not have authorization to access or modify this patient onboarding session."
}

4. Authentication Error Responses

Missing Credentials (HTTP 401)

Triggered when no Authorization or X-API-Key header is present:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

{
  "detail": "Authentication credentials required. Please provide X-API-Key or Bearer token."
}

Invalid Token (HTTP 401)

Triggered when an invalid token string is provided:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

{
  "detail": "Invalid authentication token or API key."
}

2.5 KiB Raw Blame History