# Authentication & Patient Security Specification

**Module**: API Security & Identity Management  
**Implementation Source**: [`app/core/security.py`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/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:
```http
Authorization: Bearer <ACCESS_TOKEN>
```

### Method B: `X-API-Key` Custom Header
Send the API key in the custom `X-API-Key` header:
```http
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**:
1. 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`).
2. Subsequent requests to `/message`, `/turn`, `/upload`, or `/complete` verify that the caller's authenticated `patient_id` matches the session owner.
3. If Client B attempts to send a message to Client A's session, the server immediately returns **`HTTP 403 Forbidden`**:
   ```json
   {
     "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
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
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

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