Consent Management Domain
Overview
The consent-data API in this repo is the customer-facing entry point for Lita’s consent lifecycle, token issuance, consent-scoped snapshot persistence, and scoring idempotency. The FastAPI router in backend/src/interface/lita_endpoints.py exposes the full flow under /api/lita/v1, while backend/src/models/consent.py keeps the legacy ConsentGrantModel import path available for consent-related code.
For a customer, the flow is simple: create a consent, exchange that consent for an access token, store and later read a versioned data snapshot, and submit score requests that are deduplicated by request_id. The local verification guide ties those pieces together with pytest, uvicorn, curl, and the SQLite fallback used when DATABASE_URL is not set.
Architecture Overview
flowchart TB
subgraph APILayer[API Layer]
Router[Lita endpoints router]
ConsentCreate[register_consent]
ConsentRead[get_consent]
TokenIssue[issue_token]
SnapshotWrite[store_snapshot]
SnapshotRead[read_snapshot]
ScoreRun[score_application]
Guard[_get_consent_and_token]
Serialise[_serialise_consent]
end
subgraph BusinessRules[Request Lifecycle Rules]
ConsentUTC[Consent expiry UTC normalisation]
TokenUTC[Token expiry UTC validation]
SnapshotVersion[Versioned snapshot write]
DecisionCache[Decision cache by request_id]
end
subgraph PersistenceLayer[Persistence Layer]
Repo[LitaRepository]
DB[(SQLite or MySQL)]
end
subgraph LocalVerification[Local Verification]
Pytest[pytest backend tests]
Uvicorn[uvicorn src.main app]
Curl[curl smoke flow]
Smoke[scripts lita_smoke_test.sh]
end
Router --> ConsentCreate
Router --> ConsentRead
Router --> TokenIssue
Router --> SnapshotWrite
Router --> SnapshotRead
Router --> ScoreRun
ConsentCreate --> ConsentUTC
TokenIssue --> ConsentUTC
SnapshotWrite --> Guard
SnapshotRead --> Guard
SnapshotWrite --> SnapshotVersion
SnapshotRead --> SnapshotVersion
ScoreRun --> DecisionCache
ConsentCreate --> Repo
ConsentRead --> Repo
TokenIssue --> Repo
Guard --> Repo
SnapshotWrite --> Repo
SnapshotRead --> Repo
ScoreRun --> Repo
Repo --> DB
Pytest --> Router
Uvicorn --> Router
Curl --> Router
Smoke --> Pytest
Smoke --> Uvicorn
Smoke --> Curl
Component Structure
1. API Layer
backend/src/interface/lita_endpoints.py
This file contains the router, request and response models, the bearer-token guard, and the endpoint handlers for consent creation, token issuance, snapshot persistence, snapshot retrieval, and scoring.
Public methods
| Method | Description |
|---|---|
register_consent |
Creates a consent record and returns the serialised consent response. |
get_consent |
Fetches a consent by consent_reference and serialises it for the API response. |
issue_token |
Issues an access token for an existing consent. |
store_snapshot |
Persists a versioned data snapshot under an authenticated consent. |
read_snapshot |
Reads the latest snapshot for an authenticated consent. |
score_application |
Computes or reuses a score decision keyed by request_id. |
Request and response helpers
| Method | Description |
|---|---|
_serialise_consent |
Converts a repository model into ConsentResponse, decoding JSON text fields for data_categories and refresh_permissions. |
_get_consent_and_token |
Validates the bearer token, resolves the linked consent, and enforces token and consent expiry and revocation checks. |
get_repository |
Builds a LitaRepository from the injected SQLAlchemy session. |
Dependency injection and runtime guards
| Type | Description |
|---|---|
get_db |
Supplies the SQLAlchemy Session used to build LitaRepository. |
LitaRepository |
Handles consent, token, snapshot, and score persistence. |
HTTPBearer |
Extracts the bearer token for snapshot write and read endpoints. |
IntegrityError |
Converts duplicate consent creation into 409 Conflict. |
2. Request and Response Models
ConsentRequest
backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
consent_reference |
str |
Unique consent identifier supplied by the caller. |
customer_reference |
str |
Customer-side reference for the consent. |
applicant_reference |
Optional[str] |
Optional applicant reference. |
country |
Optional[str] |
Optional country code attached to the consent. |
product_type |
Optional[str] |
Optional product type associated with the consent. |
data_categories |
List[str] |
Declared data categories to persist with the consent. |
refresh_permissions |
List[str] |
Refresh permissions stored with the consent. |
expires_at |
datetime |
Consent expiry timestamp. |
refresh_allowed |
bool |
Flag controlling whether refresh is allowed. |
ConsentResponse
backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
consent_reference |
str |
Consent identifier returned to the caller. |
customer_reference |
str |
Customer-side consent reference. |
applicant_reference |
Optional[str] |
Applicant reference echoed from storage. |
country |
Optional[str] |
Country associated with the consent. |
product_type |
Optional[str] |
Product type associated with the consent. |
data_categories |
List[str] |
Decoded consent data categories. |
refresh_permissions |
List[str] |
Decoded refresh permissions. |
expires_at |
datetime |
Stored consent expiry timestamp. |
refresh_allowed |
bool |
Refresh permission flag. |
revoked_at |
Optional[datetime] |
Revocation timestamp when present. |
created_at |
Optional[datetime] |
Creation timestamp when present. |
updated_at |
Optional[datetime] |
Last update timestamp when present. |
TokenRequest
backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
expires_in_days |
int |
Lifetime requested for the issued access token. |
TokenResponse
backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
consent_reference |
str |
Consent reference used for issuance. |
access_token |
str |
Issued access token value. |
expires_at |
datetime |
Token expiry timestamp. |
SnapshotRequest
backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
version |
str |
Snapshot version label, defaults to 1.1. |
payload |
Dict[str, Any] |
Arbitrary consent-scoped snapshot payload. |
SnapshotResponse
backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
consent_reference |
str |
Consent reference that owns the snapshot. |
version |
str |
Snapshot version label. |
stored_at |
datetime |
Timestamp returned from persistence. |
payload |
Dict[str, Any] |
Snapshot payload returned from storage or request echo. |
Applicant
backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
applicant_reference |
str |
Applicant reference supplied with the score request. |
country |
str |
Applicant country. |
ScoreContext
backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
product_type |
str |
Product type used by scoring logic. |
ModelMetadata
backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
name |
str |
Model name returned in the score response. |
version |
str |
Model version returned in the score response. |
ScoreRequest
backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
version |
str |
Request version. |
request_id |
str |
Idempotency key used by the scoring repository cache. |
applicant |
Applicant |
Applicant identity payload. |
context |
ScoreContext |
Scoring context payload. |
features |
Dict[str, Any] |
Feature map used by _compute_score. |
ScoreResponse
backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
version |
str |
Response version. |
request_id |
str |
Echoed request id. |
score |
int |
Computed numeric score. |
decision |
str |
Final decision string. |
approved_limit |
int |
Approved limit returned by the score logic. |
model |
ModelMetadata |
Model metadata for the response. |
reasons |
List[ReasonCode] |
Score reason codes returned by the scorer. |
ReasonCode
The implementation uses ReasonCode in ScoreResponse.reasons. The response examples and testing flow show reason objects with a code field such as HIGH_UTILIZATION and SHORT_HISTORY.
3. Persistence and Model Alias
backend/src/models/consent.py
This module preserves the legacy consent model import path.
| Export | Description |
|---|---|
ConsentGrantModel |
Alias imported from src.infra.mysql.models.ConsentGrantModel. |
4. Endpoint Integration
Register Consent
{
"title": "Register Consent",
"description": "Creates a consent record with data categories, refresh permissions, and expiry. Duplicate consent_reference values return 409.",
"method": "POST",
"baseUrl": "<LitaConsentApiBaseUrl>",
"endpoint": "/api/lita/v1/consents",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"consent_reference\": \"consent_local_001\",\n \"customer_reference\": \"customer_abc\",\n \"applicant_reference\": \"applicant_xyz\",\n \"country\": \"GB\",\n \"product_type\": \"CREDIT_CARD\",\n \"data_categories\": [\n \"balances\",\n \"transactions\"\n ],\n \"refresh_permissions\": [\n \"balances:read\",\n \"transactions:read\"\n ],\n \"expires_at\": \"2030-01-01T00:00:00Z\",\n \"refresh_allowed\": true\n}",
"formData": [],
"rawBody": "",
"responses": {
"201": {
"description": "Consent created",
"body": "{\n \"consent_reference\": \"consent_local_001\",\n \"customer_reference\": \"customer_abc\",\n \"applicant_reference\": \"applicant_xyz\",\n \"country\": \"GB\",\n \"product_type\": \"CREDIT_CARD\",\n \"data_categories\": [\n \"balances\",\n \"transactions\"\n ],\n \"refresh_permissions\": [\n \"balances:read\",\n \"transactions:read\"\n ],\n \"expires_at\": \"2030-01-01T00:00:00Z\",\n \"refresh_allowed\": true,\n \"revoked_at\": null,\n \"created_at\": \"2026-04-26T12:00:00Z\",\n \"updated_at\": \"2026-04-26T12:00:00Z\"\n}"
},
"409": {
"description": "Consent reference already exists",
"body": "{\n \"detail\": \"Consent reference already exists\"\n}"
}
}
}
Get Consent
{
"title": "Get Consent",
"description": "Fetches a stored consent by consent_reference and returns the serialised consent state.",
"method": "GET",
"baseUrl": "<LitaConsentApiBaseUrl>",
"endpoint": "/api/lita/v1/consents/{consent_reference}",
"headers": [],
"queryParams": [],
"pathParams": [
{
"key": "consent_reference",
"value": "consent_local_001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Consent found",
"body": "{\n \"consent_reference\": \"consent_local_001\",\n \"customer_reference\": \"customer_abc\",\n \"applicant_reference\": \"applicant_xyz\",\n \"country\": \"GB\",\n \"product_type\": \"CREDIT_CARD\",\n \"data_categories\": [\n \"balances\",\n \"transactions\"\n ],\n \"refresh_permissions\": [\n \"balances:read\",\n \"transactions:read\"\n ],\n \"expires_at\": \"2030-01-01T00:00:00Z\",\n \"refresh_allowed\": true,\n \"revoked_at\": null,\n \"created_at\": \"2026-04-26T12:00:00Z\",\n \"updated_at\": \"2026-04-26T12:00:00Z\"\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"detail\": \"Consent not found\"\n}"
}
}
}
Issue Token
{
"title": "Issue Access Token",
"description": "Creates an access token for an existing consent and returns its expiry timestamp.",
"method": "POST",
"baseUrl": "<LitaConsentApiBaseUrl>",
"endpoint": "/api/lita/v1/consents/{consent_reference}/tokens",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_reference",
"value": "consent_local_001",
"required": true
}
],
"bodyType": "json",
"requestBody": "{\n \"expires_in_days\": 30\n}",
"formData": [],
"rawBody": "",
"responses": {
"201": {
"description": "Token issued",
"body": "{\n \"consent_reference\": \"consent_local_001\",\n \"access_token\": \"6a9f6b39-3c77-4f14-9b4a-5e37ff5d4c4a\",\n \"expires_at\": \"2030-02-01T00:00:00Z\"\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"detail\": \"Consent not found\"\n}"
}
}
}
Store Snapshot
{
"title": "Store Snapshot",
"description": "Persists a versioned payload for the consent identified by the bearer token and returns the stored payload echo.",
"method": "POST",
"baseUrl": "<LitaConsentApiBaseUrl>",
"endpoint": "/api/lita/v1/data/snapshots",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"version\": \"1.1\",\n \"payload\": {\n \"balances\": {\n \"available\": 1500,\n \"currency\": \"GBP\"\n },\n \"transactions\": [\n {\n \"amount\": -20,\n \"description\": \"Coffee\"\n },\n {\n \"amount\": -50,\n \"description\": \"Groceries\"\n }\n ]\n }\n}",
"formData": [],
"rawBody": "",
"responses": {
"201": {
"description": "Snapshot stored",
"body": "{\n \"consent_reference\": \"consent_local_001\",\n \"version\": \"1.1\",\n \"stored_at\": \"2026-04-26T12:00:00Z\",\n \"payload\": {\n \"balances\": {\n \"available\": 1500,\n \"currency\": \"GBP\"\n },\n \"transactions\": [\n {\n \"amount\": -20,\n \"description\": \"Coffee\"\n },\n {\n \"amount\": -50,\n \"description\": \"Groceries\"\n }\n ]\n }\n}"
},
"401": {
"description": "Missing, invalid, or expired bearer token",
"body": "{\n \"detail\": \"Bearer token required\"\n}"
},
"403": {
"description": "Token revoked, consent revoked, or consent expired",
"body": "{\n \"detail\": \"Token revoked\"\n}"
},
"404": {
"description": "Token consent relationship missing or consent not found",
"body": "{\n \"detail\": \"Consent not found\"\n}"
}
}
}
Get Latest Snapshot
{
"title": "Get Latest Snapshot",
"description": "Returns the most recent versioned snapshot for the consent identified by the bearer token.",
"method": "GET",
"baseUrl": "<LitaConsentApiBaseUrl>",
"endpoint": "/api/lita/v1/data/snapshots/latest",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Latest snapshot returned",
"body": "{\n \"consent_reference\": \"consent_local_001\",\n \"version\": \"1.1\",\n \"stored_at\": \"2026-04-26T12:00:00Z\",\n \"payload\": {\n \"balances\": {\n \"available\": 1500,\n \"currency\": \"GBP\"\n },\n \"transactions\": [\n {\n \"amount\": -20,\n \"description\": \"Coffee\"\n },\n {\n \"amount\": -50,\n \"description\": \"Groceries\"\n }\n ]\n }\n}"
},
"401": {
"description": "Missing, invalid, or expired bearer token",
"body": "{\n \"detail\": \"Bearer token required\"\n}"
},
"403": {
"description": "Token revoked, consent revoked, or consent expired",
"body": "{\n \"detail\": \"Consent revoked\"\n}"
},
"404": {
"description": "No snapshot stored for this consent",
"body": "{\n \"detail\": \"No data available for consent\"\n}"
}
}
}
Score Application
{
"title": "Score Application",
"description": "Computes a score for the supplied request_id or returns the cached decision for that request_id. The implementation caches by ScoreRequest.request_id, not by request header.",
"method": "POST",
"baseUrl": "<LitaConsentApiBaseUrl>",
"endpoint": "/api/lita/v1/score",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"version\": \"1.1\",\n \"request_id\": \"req-lita-123\",\n \"applicant\": {\n \"applicant_reference\": \"app-100\",\n \"country\": \"GB\"\n },\n \"context\": {\n \"product_type\": \"CREDIT_CARD\"\n },\n \"features\": {\n \"credit_utilization\": 0.65,\n \"debt_to_income_ratio\": 0.4,\n \"credit_history_months\": 30,\n \"monthly_income\": 6000,\n \"delinquencies_last_24m\": 0\n }\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Score returned",
"body": "{\n \"version\": \"1.1\",\n \"request_id\": \"req-lita-123\",\n \"score\": 712,\n \"decision\": \"APPROVE\",\n \"approved_limit\": 4000,\n \"model\": {\n \"name\": \"lita_consent_scoring\",\n \"version\": \"1.1.0\"\n },\n \"reasons\": [\n {\n \"code\": \"HIGH_UTILIZATION\"\n },\n {\n \"code\": \"SHORT_HISTORY\"\n }\n ]\n}"
}
}
}
Feature Flows
1. Consent Creation
sequenceDiagram
participant C as Customer
participant API as Lita router
participant R as LitaRepository
participant DB as Database
C->>API: POST /api/lita/v1/consents
API->>API: register_consent
API->>API: normalise expires_at to UTC
API->>R: create_consent
R->>DB: insert consent row
DB-->>R: stored consent model
R-->>API: consent model
API->>API: _serialise_consent
API-->>C: 201 ConsentResponse
2. Access Token Issuance
sequenceDiagram
participant C as Customer
participant API as Lita router
participant R as LitaRepository
participant DB as Database
C->>API: POST /api/lita/v1/consents/{consent_reference}/tokens
API->>R: get_consent
R->>DB: fetch consent by reference
DB-->>R: consent or null
R-->>API: consent
API->>API: compute expires_at from expires_in_days
API->>R: issue_access_token
R->>DB: insert access token row
DB-->>R: token model
R-->>API: token model
API-->>C: 201 TokenResponse
3. Snapshot Write and Read
sequenceDiagram
participant C as Customer
participant API as Lita router
participant Guard as _get_consent_and_token
participant R as LitaRepository
participant DB as Database
C->>API: POST /api/lita/v1/data/snapshots
API->>Guard: Depends on bearer token
Guard->>R: get_access_token
R->>DB: fetch token by value
DB-->>R: token or null
R-->>Guard: token record
Guard->>R: get_consent_by_id
R->>DB: fetch consent by id
DB-->>R: consent or null
R-->>Guard: consent
Guard-->>API: consent and token
API->>R: record_snapshot
R->>DB: insert snapshot row
DB-->>R: snapshot model
R-->>API: snapshot model
API-->>C: 201 SnapshotResponse
C->>API: GET /api/lita/v1/data/snapshots/latest
API->>Guard: Depends on bearer token
Guard->>R: get_access_token
R->>DB: fetch token by value
DB-->>R: token or null
R-->>Guard: token record
Guard->>R: get_consent_by_id
R->>DB: fetch consent by id
DB-->>R: consent or null
R-->>Guard: consent
Guard-->>API: consent and token
API->>R: latest_snapshot
R->>DB: fetch newest snapshot for consent
DB-->>R: snapshot model or null
R-->>API: snapshot model
API-->>C: 200 SnapshotResponse
4. Score Idempotency
sequenceDiagram
participant C as Customer
participant API as Lita router
participant R as LitaRepository
participant DB as Database
C->>API: POST /api/lita/v1/score
API->>R: get_decision(request_id)
R->>DB: fetch cached decision
DB-->>R: cached payload or null
alt cache hit
R-->>API: cached payload
API-->>C: 200 ScoreResponse
else cache miss
API->>API: _compute_score
API->>API: derive decision and reasons
API->>R: save_decision(request_id, payload)
R->>DB: insert decision row
DB-->>R: saved decision
R-->>API: saved decision
API-->>C: 200 ScoreResponse
end
State Management
Consent and token lifecycle states
| State | Description |
|---|---|
active |
Consent or token can be used while within expiry and not revoked. |
revoked |
revoked_at is populated and access is rejected. |
expired |
expires_at is earlier than the current UTC time. |
missing |
Repository lookup returns no consent, token, or snapshot. |
Score decision reuse
| State | Description |
|---|---|
uncached |
No stored decision exists for the supplied request_id. |
cached |
A stored decision is returned directly from repository.get_decision. |
Snapshot versioning
| State | Description |
|---|---|
written |
record_snapshot has stored a consent-scoped snapshot row. |
latest |
latest_snapshot returns the newest stored row for the consent. |
Error Handling
[!NOTE]
documents/lita-consent-data-api.mddescribes idempotency usingX-Request-Id, but the implementedscore_applicationhandler readsScoreRequest.request_idfrom the JSON body and caches withrepository.get_decision(body.request_id).
The route handlers convert repository and validation failures into explicit HTTP responses. register_consent normalises naive expiry timestamps to UTC and returns 409 Conflict when the repository raises IntegrityError for an existing consent_reference.
try:
consent = repository.create_consent(...)
except IntegrityError:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="Consent reference already exists",
)
The bearer-token guard performs the full access chain before a snapshot handler runs:
401 Unauthorizedwhen the bearer header is missing or not a Bearer scheme.401 Unauthorizedwhen the access token cannot be resolved.403 Forbiddenwhen the token is revoked.401 Unauthorizedwhen the token is expired.404 Not Foundwhen the consent is missing.403 Forbiddenwhen the consent is revoked.403 Forbiddenwhen the consent is expired.
For snapshots, a missing latest record produces 404 Not Found with No data available for consent.
Persistence Expectations
documents/lita-implementation-overview.md describes the storage contract behind this API:
LitaConsentModelstores consent metadata, expiry, and revocation timestamp.LitaAccessTokenModelstores issued tokens scoped to a consent, with expiry and optional revocation.LitaDataSnapshotModelstores versioned JSON payloads per consent.LitaScoreDecisionModelstores cached scoring decisions keyed byrequest_id.
The same overview also states that JSON-like fields are persisted as text and reconstructed with json.dumps and json.loads. That matches the router’s _serialise_consent helper, which decodes data_categories and refresh_permissions with json.loads, and read_snapshot, which decodes snapshot.payload with json.loads.
Local Verification Flow
Quick verification commands
- Create and activate a virtual environment, then install backend dependencies.
python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
- Start the FastAPI app.
cd backend
uvicorn src.main:app --host 0.0.0.0 --reload --port 8000
- Create a consent.
curl -X POST http://localhost:8000/api/lita/v1/consents \
-H "Content-Type: application/json" \
-d '{
"consent_reference": "consent_local_001",
"customer_reference": "customer_abc",
"applicant_reference": "applicant_xyz",
"country": "GB",
"product_type": "CREDIT_CARD",
"data_categories": ["balances", "transactions"],
"refresh_permissions": ["balances:read", "transactions:read"],
"expires_at": "2030-01-01T00:00:00Z",
"refresh_allowed": true
}'
- Issue an access token.
curl -X POST http://localhost:8000/api/lita/v1/consents/consent_local_001/tokens \
-H "Content-Type: application/json" \
-d '{"expires_in_days": 30}'
- Store a snapshot.
curl -X POST http://localhost:8000/api/lita/v1/data/snapshots \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"version": "1.1",
"payload": {
"balances": {"available": 1500, "currency": "GBP"},
"transactions": [
{"amount": -20, "description": "Coffee"},
{"amount": -50, "description": "Groceries"}
]
}
}'
- Read the latest snapshot.
curl -X GET http://localhost:8000/api/lita/v1/data/snapshots/latest \
-H "Authorization: Bearer <ACCESS_TOKEN>"
- Call the score endpoint twice with the same
request_id.
curl -X POST http://localhost:8000/api/lita/v1/score \
-H "Content-Type: application/json" \
-d '{
"version": "1.1",
"request_id": "req-demo-001",
"applicant": {"applicant_reference": "app-100", "country": "GB"},
"context": {"product_type": "CREDIT_CARD"},
"features": {
"credit_utilization": 0.65,
"debt_to_income_ratio": 0.4,
"credit_history_months": 30,
"monthly_income": 6000
}
}'
SQLite fallback behavior
documents/lita-testing-guide.md states that local runs use sqlite:///./app.db when DATABASE_URL is not set. The same guide’s smoke-test script runs the consent, token, snapshot, and scoring flow against that fallback, so local verification does not require MySQL for the basic path.
Targeted regression test
pytest backend/tests/interface/test_lita_endpoints.py -q
That test module covers:
- consent registration
- access token issuance
- snapshot round-trip persistence
- score idempotency with repeated
request_id
One-shot smoke test
./scripts/lita_smoke_test.sh
The script:
- runs the targeted pytest module
- starts uvicorn against the SQLite fallback
- creates a consent
- issues a token
- stores and reads a snapshot
- exercises scoring twice to confirm idempotency
If dependencies are missing, the script bootstraps them from backend/requirements.txt. Set LITA_BOOTSTRAP_DEPS=0 to disable that install step.
Testing Considerations
| Scenario | Expected result |
|---|---|
Duplicate consent_reference |
409 Conflict from consent creation. |
| Missing bearer token on snapshot routes | 401 Unauthorized. |
| Revoked or expired token | 403 Forbidden or 401 Unauthorized depending on the failure stage. |
| Missing consent for token | 404 Not Found. |
| Missing latest snapshot | 404 Not Found. |
Repeated score request with same request_id |
Identical ScoreResponse from the repository cache. |
No DATABASE_URL locally |
SQLite file at sqlite:///./app.db. |
Dependencies
| Dependency | Role in this domain |
|---|---|
fastapi |
Router, dependency injection, HTTP exceptions, and bearer auth extraction. |
pydantic |
Request and response model definitions. |
sqlalchemy |
Session injection and IntegrityError handling. |
json |
Consent and snapshot payload decoding. |
datetime, timedelta, timezone |
Consent, token, and snapshot timestamp handling. |
LitaRepository |
Persistence and score decision caching. |
get_db |
SQLAlchemy session provider used by get_repository. |
Key Classes Reference
| Class | Responsibility |
|---|---|
lita_endpoints.py |
FastAPI router, consent/token/snapshot/score handlers, and API models. |
consent.py |
Compatibility alias for ConsentGrantModel. |
lita-consent-data-api.md |
Customer-facing consent-data API contract and persistence expectations. |
lita-testing-guide.md |
Local verification steps, SQLite fallback usage, and smoke-test flow. |