80 lines
2.5 KiB
Markdown
80 lines
2.5 KiB
Markdown
# 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."
|
|
}
|
|
```
|