Architecture and Repository Orientation
Overview
This section maps the repository’s cross-service contract surfaces: the FastAPI routers that expose consent, data, scoring, open-banking, and Japan credit workflows; the Next.js API-route proxies that front applicant data calls; and the customer-facing documents that define the contract language for consent, tokens, snapshots, scoring, versioning, and idempotency.
The repository separates transport concerns from business rules in a way that makes the contract boundary easy to find. backend/src/interface/*.py files define the HTTP surface and model schemas, backend/src/usecase/*.py files implement the rules behind those endpoints, frontend/app/api/**/*.ts proxies and reshapes a subset of backend calls, and documents/*.md files describe the customer-facing expectations that those routes are meant to satisfy.
Architecture Overview
flowchart TB
Client[Customer or operator client]
subgraph ContractDocs[Contract Documents]
LitaConsentDoc[lita consent data api]
UsApiDoc[us api v1]
ImplOverview[lita implementation overview]
end
subgraph NextJsProxy[Next.js API Routes]
CoverageRoute[account coverage route]
TransactionsRoute[transactions route]
end
subgraph FastApiBackend[FastAPI Backend]
LitaRouter[lita endpoints router]
OpenBankingRouter[open banking endpoints router]
JapanCreditRouter[japan credit endpoints router]
end
subgraph Persistence[Persistence and External Systems]
LitaRepo[Lita repository]
OpenBankingRepo[Open banking repository]
JapanCreditRepo[Japan credit repositories]
DB[(Database)]
end
Client --> NextJsProxy
Client --> FastApiBackend
LitaConsentDoc -.-> LitaRouter
UsApiDoc -.-> FastApiBackend
ImplOverview -.-> LitaRouter
CoverageRoute -->|GET account coverage| FastApiBackend
TransactionsRoute -->|GET transactions| FastApiBackend
LitaRouter --> LitaRepo
OpenBankingRouter --> OpenBankingRepo
JapanCreditRouter --> JapanCreditRepo
LitaRepo --> DB
OpenBankingRepo --> DB
JapanCreditRepo --> DB
Contract Sources and Versioning
[!IMPORTANT] The contract language is split across runtime routes and documents. The implementation routes under
/api/lita/v1,/open-banking, and/api/japan-creditare the live FastAPI surfaces, whiledocuments/lita-consent-data-api.md,documents/us-api-v1.md, anddocuments/lita-implementation-overview.mddescribe the public contract terms, versioning, and idempotency rules that those surfaces follow.
The repository uses the documents under documents/ as the contract layer and the interface modules under backend/src/interface/ as the runtime layer.
| Source | Scope | Contract rule carried by the source |
|---|---|---|
documents/lita-consent-data-api.md |
Consent-based data access and scoring | Semantic versioning, /api/v1/... contract examples, X-Request-Id idempotency for the customer-hosted scoring API |
documents/us-api-v1.md |
US-specific consent, token, data, feature, webhook, and replay contract | /api/v1/us/... namespace, semantic versioning, backward-compatible minor changes, explicit purpose and category rules |
documents/lita-implementation-overview.md |
Implementation behavior reference | Maps the public contract to the implemented /api/lita/v1 routes, database-backed consent/token/snapshot/score persistence, request-id caching |
backend/src/interface/lita_endpoints.py |
Live Lita consent, token, data snapshot, and score endpoints | Router prefix /api/lita/v1 |
backend/src/interface/open_banking_endpoints.py |
Live open-banking consent and Plaid orchestration endpoints | Router prefix /open-banking |
backend/src/interface/japan_credit_endpoints.py |
Live staff-initiated Japan credit consent endpoints | Router prefix /api/japan-credit |
Versioning model
documents/lita-consent-data-api.mddeclares semantic versioning and uses contract examples under/api/v1/....documents/us-api-v1.mddeclares semantic versioning and explicitly namespaces the US contract under/api/v1/us/.backend/src/interface/lita_endpoints.pyimplements its live router prefix as/api/lita/v1.- The scoring request/response contract in
backend/src/interface/lita_endpoints.pycarries aversionfield in the payload and echoes that sameversionin the response. - Idempotency is split by contract surface:
documents/lita-consent-data-api.mdusesX-Request-Idfor the customer-hosted scoring API.backend/src/interface/lita_endpoints.pycaches scoring decisions byrequest_idin the request body.
Lita Consent, Token, Snapshot, and Scoring Surface
File: backend/src/interface/lita_endpoints.py
This module is the main Lita contract surface for consent creation, consent lookup, token issuance, data snapshot write/read, and scoring. The router is defined with prefix /api/lita/v1, and token-gated routes depend on _get_consent_and_token, which validates bearer credentials, token status, token expiry, consent status, and consent expiry before allowing snapshot access.
Handler methods
| Method | Description |
|---|---|
register_consent |
Creates a consent record and maps duplicate consent references to 409 Conflict |
get_consent |
Returns a serialized consent by consent_reference or 404 if missing |
issue_token |
Issues a scoped access token for an existing consent |
store_snapshot |
Stores a versioned data snapshot for the authenticated consent |
read_snapshot |
Returns the latest stored snapshot for the authenticated consent |
score_application |
Computes or returns a cached scoring decision keyed by request_id |
Request and response models
Consent Request
File: backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
consent_reference |
str |
External consent identifier |
customer_reference |
str |
Customer identifier |
applicant_reference |
Optional[str] |
Optional applicant identifier |
country |
Optional[str] |
Optional country code |
product_type |
Optional[str] |
Optional product type |
data_categories |
List[str] |
Consent-scoped data categories |
refresh_permissions |
List[str] |
Consent-scoped refresh permissions |
expires_at |
datetime |
Consent expiry timestamp |
refresh_allowed |
bool |
Refresh permission flag |
Consent Response
File: backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
consent_reference |
str |
Consent identifier |
customer_reference |
str |
Customer identifier |
applicant_reference |
Optional[str] |
Applicant identifier |
country |
Optional[str] |
Country code |
product_type |
Optional[str] |
Product type |
data_categories |
List[str] |
Stored data categories |
refresh_permissions |
List[str] |
Stored refresh permissions |
expires_at |
datetime |
Consent expiry timestamp |
refresh_allowed |
bool |
Refresh flag |
revoked_at |
Optional[datetime] |
Revocation timestamp |
created_at |
Optional[datetime] |
Creation timestamp |
updated_at |
Optional[datetime] |
Update timestamp |
Token Request
File: backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
expires_in_days |
int |
Token lifetime in days |
Token Response
File: backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
consent_reference |
str |
Consent identifier |
access_token |
str |
Issued bearer token |
expires_at |
datetime |
Token expiry timestamp |
Snapshot Request
File: backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
version |
str |
Snapshot contract version |
payload |
Dict[str, Any] |
JSON payload persisted as the snapshot body |
Snapshot Response
File: backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
consent_reference |
str |
Consent identifier |
version |
str |
Stored snapshot version |
stored_at |
datetime |
Snapshot creation timestamp |
payload |
Dict[str, Any] |
Stored snapshot payload |
Applicant
File: backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
applicant_reference |
str |
Applicant reference |
country |
str |
Applicant country |
Score Request
File: backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
version |
str |
Scoring contract version |
request_id |
str |
Idempotency key for decision caching |
applicant |
Applicant |
Applicant identity payload |
context |
ScoreContext |
Scoring context payload |
features |
Dict[str, Any] |
Feature map used by the scoring rule |
Score Response
File: backend/src/interface/lita_endpoints.py
| Property | Type | Description |
|---|---|---|
version |
str |
Response version |
request_id |
str |
Echoed request identifier |
score |
int |
Numeric score |
decision |
str |
Final decision |
approved_limit |
int |
Approved limit returned by the rule |
model |
ModelMetadata |
Model metadata payload |
reasons |
List[ReasonCode] |
Reason code list |
Endpoint details
Register Consent
{
"title": "Register Consent",
"description": "Creates a new consent record with stored categories, refresh permissions, expiry, and optional applicant metadata",
"method": "POST",
"baseUrl": "<LitaBackendApiBaseUrl>",
"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\": \"2025-03-31T10:15:00Z\",\n \"updated_at\": \"2025-03-31T10:15:00Z\"\n}"
},
"409": {
"description": "Consent reference already exists",
"body": "{\n \"detail\": \"Consent reference already exists\"\n}"
}
}
}
Get Consent
{
"title": "Get Consent",
"description": "Returns stored consent metadata by consent reference",
"method": "GET",
"baseUrl": "<LitaBackendApiBaseUrl>",
"endpoint": "/api/lita/v1/consents/{consent_reference}",
"headers": [],
"queryParams": [],
"pathParams": [
{
"name": "consent_reference",
"type": "string",
"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\": \"2025-03-31T10:15:00Z\",\n \"updated_at\": \"2025-03-31T10:15:00Z\"\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"detail\": \"Consent not found\"\n}"
}
}
}
Issue Token
{
"title": "Issue Token",
"description": "Issues a bearer access token tied to an existing consent and returns its expiry",
"method": "POST",
"baseUrl": "<LitaBackendApiBaseUrl>",
"endpoint": "/api/lita/v1/consents/{consent_reference}/tokens",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"name": "consent_reference",
"type": "string",
"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\": \"tok_5f6a4f1e9d2a4c0d\",\n \"expires_at\": \"2025-04-30T10:15:00Z\"\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"detail\": \"Consent not found\"\n}"
}
}
}
Store Snapshot
{
"title": "Store Snapshot",
"description": "Stores a versioned JSON snapshot after bearer token and consent validity checks pass",
"method": "POST",
"baseUrl": "<LitaBackendApiBaseUrl>",
"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\": \"2025-03-31T10:20: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": "Bearer token missing, invalid, or expired",
"body": "{\n \"detail\": \"Token expired\"\n}"
},
"403": {
"description": "Token revoked or consent revoked or expired",
"body": "{\n \"detail\": \"Consent revoked\"\n}"
},
"404": {
"description": "Consent not found or no token-linked consent",
"body": "{\n \"detail\": \"Consent not found\"\n}"
}
}
}
Get Latest Snapshot
{
"title": "Get Latest Snapshot",
"description": "Returns the latest stored snapshot for the authenticated consent",
"method": "GET",
"baseUrl": "<LitaBackendApiBaseUrl>",
"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\": \"2025-03-31T10:20: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": "Bearer token missing, invalid, or expired",
"body": "{\n \"detail\": \"Invalid access token\"\n}"
},
"403": {
"description": "Token revoked, consent revoked, or consent expired",
"body": "{\n \"detail\": \"Consent expired\"\n}"
},
"404": {
"description": "No snapshot exists for the consent",
"body": "{\n \"detail\": \"No data available for consent\"\n}"
}
}
}
Score Application
{
"title": "Score Application",
"description": "Computes or replays a cached scoring decision using the request_id idempotency key",
"method": "POST",
"baseUrl": "<LitaBackendApiBaseUrl>",
"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 \"delinquencies_last_24m\": 0,\n \"monthly_income\": 6000\n }\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Score computed or replayed from cache",
"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}"
}
}
}
Contract and execution notes
register_consenttranslates database uniqueness failures into409 Conflict.get_consentreturns404when the reference is not found.issue_tokenusesdatetime.now(timezone.utc) + timedelta(days=body.expires_in_days)to compute expiry._get_consent_and_tokenenforces the entire credential chain before snapshot operations:- bearer scheme must be present
- access token must exist
- token must not be revoked
- token must not be expired
- consent must exist
- consent must not be revoked
- consent must not be expired
score_applicationfirst checksrepository.get_decision(body.request_id)and returns the stored payload immediately when present.
Feature flow: consent to score to snapshot
sequenceDiagram
participant Client as Client
participant Router as Lita Router
participant Repo as Lita Repository
participant DB as Database
Client->>Router: POST /api/lita/v1/consents
Router->>Repo: create_consent
Repo->>DB: insert consent row
DB-->>Repo: consent row
Repo-->>Router: consent model
Router-->>Client: 201 ConsentResponse
Client->>Router: POST /api/lita/v1/consents/consent_local_001/tokens
Router->>Repo: get_consent
Repo->>DB: select consent row
DB-->>Repo: consent row
Repo-->>Router: consent model
Router->>Repo: issue_access_token
Repo->>DB: insert token row
DB-->>Repo: token row
Repo-->>Router: token model
Router-->>Client: 201 TokenResponse
Client->>Router: POST /api/lita/v1/data/snapshots
Router->>Repo: get_access_token and get_consent
Repo->>DB: read token and consent rows
DB-->>Repo: token and consent rows
Repo-->>Router: token and consent models
Router->>Repo: record_snapshot
Repo->>DB: insert snapshot row
DB-->>Repo: snapshot row
Repo-->>Router: snapshot model
Router-->>Client: 201 SnapshotResponse
Client->>Router: POST /api/lita/v1/score
Router->>Repo: get_decision request_id
Repo->>DB: lookup decision row
DB-->>Repo: cached decision or none
Repo-->>Router: cached payload or none
alt cached decision exists
Router-->>Client: cached ScoreResponse
else cache miss
Router->>Router: compute score and reasons
Router->>Repo: save_decision request_id
Repo->>DB: insert decision row
DB-->>Repo: decision row
Repo-->>Router: saved decision
Router-->>Client: new ScoreResponse
end
Open Banking Contract Surface
[!IMPORTANT] The scoring contract uses two different idempotency conventions in the repository: the public customer-hosted scoring spec in
documents/lita-consent-data-api.mdusesX-Request-Id, while the implemented backend score endpoint caches byrequest_idin the JSON body. They serve different integration surfaces.
File: backend/src/interface/open_banking_endpoints.py
This module exposes the open-banking consent and Plaid orchestration surface. It uses SQLOpenBankingConsentRepository for persistence, BankGateway for upstream Plaid-style token exchange, and get_current_user_email to gate access to consent operations. The router prefix is /open-banking.
Handler methods
| Method | Description |
|---|---|
create_consent |
Creates a consent, merges operator access, and stores refresh settings |
create_link_token |
Generates a Plaid link token for an existing consent |
exchange_public_token |
Exchanges a public token and attaches upstream tokens to the consent |
list_application_consents |
Lists application-linked consents visible to the current operator |
sync_application_consents |
Synchronizes application-linked consents and filters them by operator access |
Request and response models
Create Consent Request
File: backend/src/interface/open_banking_endpoints.py
| Property | Type | Description |
|---|---|---|
consent_reference |
str |
Consent identifier |
customer_reference |
str |
Customer identifier |
customer_name |
Optional[str] |
Customer name |
scopes |
List[str] |
Granted scopes |
expires_at |
datetime |
Consent expiry |
allowed_operator_ids |
List[str] |
Operator allowlist |
metadata |
Optional[Dict[str, Any]] |
Arbitrary metadata |
auto_refresh_enabled |
bool |
Auto-refresh flag |
auto_refresh_interval_minutes |
int |
Refresh interval |
application_id |
Optional[int] |
Optional linked application |
Open Banking Consent Response
File: backend/src/interface/open_banking_endpoints.py
| Property | Type | Description |
|---|---|---|
consent_reference |
str |
Consent identifier |
customer_reference |
str |
Customer identifier |
customer_name |
Optional[str] |
Customer name |
application_id |
Optional[int] |
Linked application id |
scopes |
List[str] |
Granted scopes |
expires_at |
datetime |
Expiry timestamp |
revoked_at |
Optional[datetime] |
Revocation timestamp |
allowed_operator_ids |
List[str] |
Operator allowlist |
metadata |
Dict[str, Any] |
Stored metadata |
plaid_item_id |
Optional[str] |
Upstream item id |
auto_refresh_enabled |
bool |
Auto-refresh flag |
auto_refresh_interval_minutes |
int |
Refresh interval |
last_refreshed_at |
Optional[datetime] |
Last refresh timestamp |
created_at |
Optional[datetime] |
Creation timestamp |
updated_at |
Optional[datetime] |
Update timestamp |
Link Token Request
File: backend/src/interface/open_banking_endpoints.py
| Property | Type | Description |
|---|---|---|
consent_reference |
str |
Consent identifier |
Endpoint details
Create Open Banking Consent
{
"title": "Create Open Banking Consent",
"description": "Creates an open-banking consent and merges the current operator into the allowlist before persistence",
"method": "POST",
"baseUrl": "<OpenBankingApiBaseUrl>",
"endpoint": "/open-banking/consents",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"consent_reference\": \"ob_consent_001\",\n \"customer_reference\": \"customer_001\",\n \"customer_name\": \"Jane Doe\",\n \"scopes\": [\n \"balances:read\",\n \"transactions:read\"\n ],\n \"expires_at\": \"2025-12-31T00:00:00Z\",\n \"allowed_operator_ids\": [\n \"[email protected]\"\n ],\n \"metadata\": {\n \"source\": \"branch\",\n \"region\": \"JP\"\n },\n \"auto_refresh_enabled\": true,\n \"auto_refresh_interval_minutes\": 720,\n \"application_id\": 101\n}",
"formData": [],
"rawBody": "",
"responses": {
"201": {
"description": "Consent created",
"body": "{\n \"consent_reference\": \"ob_consent_001\",\n \"customer_reference\": \"customer_001\",\n \"customer_name\": \"Jane Doe\",\n \"application_id\": 101,\n \"scopes\": [\n \"balances:read\",\n \"transactions:read\"\n ],\n \"expires_at\": \"2025-12-31T00:00:00Z\",\n \"revoked_at\": null,\n \"allowed_operator_ids\": [\n \"[email protected]\"\n ],\n \"metadata\": {\n \"source\": \"branch\",\n \"region\": \"JP\"\n },\n \"plaid_item_id\": null,\n \"auto_refresh_enabled\": true,\n \"auto_refresh_interval_minutes\": 720,\n \"last_refreshed_at\": null,\n \"created_at\": \"2025-03-31T10:25:00Z\",\n \"updated_at\": \"2025-03-31T10:25:00Z\"\n}"
},
"409": {
"description": "Consent reference already exists",
"body": "{\n \"detail\": \"Consent reference already exists\"\n}"
}
}
}
Create Link Token
{
"title": "Create Link Token",
"description": "Creates a Plaid link token for an existing active consent and returns the upstream token payload",
"method": "POST",
"baseUrl": "<OpenBankingApiBaseUrl>",
"endpoint": "/open-banking/link-token",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"consent_reference\": \"ob_consent_001\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Link token created",
"body": "{\n \"link_token\": \"link-token\",\n \"expiration\": \"2099-01-01T00:00:00Z\"\n}"
},
"400": {
"description": "Consent is not active",
"body": "{\n \"detail\": \"Consent is not active\"\n}"
},
"403": {
"description": "Operator is not allowed to view the consent",
"body": "{\n \"detail\": \"You are not authorised to view these consents.\"\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"detail\": \"Consent not found\"\n}"
},
"502": {
"description": "Upstream token creation failed",
"body": "{\n \"detail\": \"Failed to create link token\"\n}"
}
}
}
Exchange Public Token
{
"title": "Exchange Public Token",
"description": "Exchanges a public token and persists the returned access token and item id against the consent",
"method": "POST",
"baseUrl": "<OpenBankingApiBaseUrl>",
"endpoint": "/open-banking/consents/{consent_reference}/exchange",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"name": "consent_reference",
"type": "string",
"required": true
}
],
"bodyType": "json",
"requestBody": "{\n \"public_token\": \"public-token\",\n \"consent_expires_at\": \"2025-12-31T00:00:00Z\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Public token exchanged",
"body": "{\n \"consent_reference\": \"ob_consent_001\",\n \"customer_reference\": \"customer_001\",\n \"customer_name\": \"Jane Doe\",\n \"application_id\": 101,\n \"scopes\": [\n \"balances:read\",\n \"transactions:read\"\n ],\n \"expires_at\": \"2025-12-31T00:00:00Z\",\n \"revoked_at\": null,\n \"allowed_operator_ids\": [\n \"[email protected]\"\n ],\n \"metadata\": {\n \"source\": \"branch\",\n \"region\": \"JP\"\n },\n \"plaid_item_id\": \"item-123\",\n \"auto_refresh_enabled\": true,\n \"auto_refresh_interval_minutes\": 720,\n \"last_refreshed_at\": null,\n \"created_at\": \"2025-03-31T10:25:00Z\",\n \"updated_at\": \"2025-03-31T10:26:00Z\"\n}"
},
"403": {
"description": "Operator is not allowed to view the consent",
"body": "{\n \"detail\": \"You are not authorised to view these consents.\"\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"detail\": \"Consent not found\"\n}"
},
"502": {
"description": "Upstream exchange failed",
"body": "{\n \"detail\": \"Failed to exchange public token\"\n}"
}
}
}
List Application Consents
{
"title": "List Application Consents",
"description": "Returns all consents linked to an application that are visible to the current operator",
"method": "GET",
"baseUrl": "<OpenBankingApiBaseUrl>",
"endpoint": "/open-banking/applications/{application_id}/consents",
"headers": [],
"queryParams": [],
"pathParams": [
{
"name": "application_id",
"type": "integer",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Consent list returned",
"body": "[\n {\n \"consent_reference\": \"ob_consent_001\",\n \"customer_reference\": \"customer_001\",\n \"customer_name\": \"Jane Doe\",\n \"application_id\": 101,\n \"scopes\": [\n \"balances:read\",\n \"transactions:read\"\n ],\n \"expires_at\": \"2025-12-31T00:00:00Z\",\n \"revoked_at\": null,\n \"allowed_operator_ids\": [\n \"[email protected]\"\n ],\n \"metadata\": {\n \"source\": \"branch\",\n \"region\": \"JP\"\n },\n \"plaid_item_id\": \"item-123\",\n \"auto_refresh_enabled\": true,\n \"auto_refresh_interval_minutes\": 720,\n \"last_refreshed_at\": null,\n \"created_at\": \"2025-03-31T10:25:00Z\",\n \"updated_at\": \"2025-03-31T10:26:00Z\"\n }\n]"
},
"403": {
"description": "No consent is visible to the current operator",
"body": "{\n \"detail\": \"You are not authorised to view these consents.\"\n}"
}
}
}
Sync Application Consents
{
"title": "Sync Application Consents",
"description": "Synchronizes application-linked consents and returns only those visible to the current operator",
"method": "POST",
"baseUrl": "<OpenBankingApiBaseUrl>",
"endpoint": "/open-banking/applications/{application_id}/consents/sync",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"name": "application_id",
"type": "integer",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Synced consent list returned",
"body": "[\n {\n \"consent_reference\": \"ob_consent_001\",\n \"customer_reference\": \"customer_001\",\n \"customer_name\": \"Jane Doe\",\n \"application_id\": 101,\n \"scopes\": [\n \"balances:read\",\n \"transactions:read\"\n ],\n \"expires_at\": \"2025-12-31T00:00:00Z\",\n \"revoked_at\": null,\n \"allowed_operator_ids\": [\n \"[email protected]\"\n ],\n \"metadata\": {\n \"source\": \"branch\",\n \"region\": \"JP\"\n },\n \"plaid_item_id\": \"item-123\",\n \"auto_refresh_enabled\": true,\n \"auto_refresh_interval_minutes\": 720,\n \"last_refreshed_at\": null,\n \"created_at\": \"2025-03-31T10:25:00Z\",\n \"updated_at\": \"2025-03-31T10:26:00Z\"\n }\n]"
},
"403": {
"description": "No consent is visible to the current operator",
"body": "{\n \"detail\": \"You are not authorised to view these consents.\"\n}"
}
}
}
Contract and execution notes
create_consentappendscurrent_user_emailto the allowed operators before persistence and de-duplicates the final list.create_link_tokenfails fast when the consent is missing, inactive, or not visible to the current operator.exchange_public_tokenpersists both the upstream access token and the item id throughattach_plaid_tokens.list_application_consentsandsync_application_consentsfilter the repository result set byconsent.ensure_operator_allowed(current_user_email)and return403when nothing remains visible.
Japan Credit Staff Pull Surface
File: backend/src/interface/japan_credit_endpoints.py
This module exposes the Japan staff-initiated credit consent contract. It uses SQLJapanCreditConsentRepository for persistence, perform_staff_credit_pull and related use cases for workflow orchestration, and returns JapanCreditConsentResponse from the shared schema module.
Handler methods
| Method | Description |
|---|---|
create_consent |
Registers a staff-initiated credit consent |
revoke_consent |
Revokes a staff-initiated credit consent |
credit_pulls |
Endpoint is declared and routed for staff credit pulls |
Request and response models
Japan Credit Consent Response
File: backend/src/interface/schemas.py
| Property | Type | Description |
|---|---|---|
id |
int |
Internal identifier |
consent_reference |
str |
Consent reference |
customer_reference |
str |
Customer reference |
customer_name |
str |
Customer name |
permissible_purpose |
str |
Bureau purpose string |
expires_at |
datetime |
Consent expiry |
revoked_at |
Optional[datetime] |
Revocation timestamp |
allowed_operator_ids |
List[str] |
Operator allowlist |
created_at |
Optional[datetime] |
Creation timestamp |
updated_at |
Optional[datetime] |
Update timestamp |
Endpoint details
Create Japan Credit Consent
{
"title": "Create Japan Credit Consent",
"description": "Registers a staff-initiated credit consent for Japan bureau workflows",
"method": "POST",
"baseUrl": "<JapanCreditApiBaseUrl>",
"endpoint": "/api/japan-credit/consents",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"consent_reference\": \"jp_consent_001\",\n \"customer_reference\": \"customer_001\",\n \"customer_name\": \"Yuki Tanaka\",\n \"permissible_purpose\": \"TENANCY_SCREENING\",\n \"expires_at\": \"2025-12-31T00:00:00Z\",\n \"allowed_operator_ids\": [\n \"[email protected]\"\n ],\n \"customer_profile\": {\n \"country\": \"JP\",\n \"branch\": \"Tokyo\"\n },\n \"metadata\": {\n \"source\": \"branch\",\n \"channel\": \"dashboard\"\n }\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Consent created",
"body": "{\n \"id\": 123,\n \"consent_reference\": \"jp_consent_001\",\n \"customer_reference\": \"customer_001\",\n \"customer_name\": \"Yuki Tanaka\",\n \"permissible_purpose\": \"TENANCY_SCREENING\",\n \"expires_at\": \"2025-12-31T00:00:00Z\",\n \"revoked_at\": null,\n \"allowed_operator_ids\": [\n \"[email protected]\"\n ],\n \"created_at\": \"2025-03-31T10:30:00Z\",\n \"updated_at\": \"2025-03-31T10:30:00Z\"\n}"
}
}
}
Revoke Japan Credit Consent
{
"title": "Revoke Japan Credit Consent",
"description": "Revokes a Japan credit consent and returns the updated consent record",
"method": "POST",
"baseUrl": "<JapanCreditApiBaseUrl>",
"endpoint": "/api/japan-credit/consents/{consent_reference}/revoke",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"name": "consent_reference",
"type": "string",
"required": true
}
],
"bodyType": "json",
"requestBody": "{\n \"revoked_at\": \"2025-03-31T10:45:00Z\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Consent revoked",
"body": "{\n \"id\": 123,\n \"consent_reference\": \"jp_consent_001\",\n \"customer_reference\": \"customer_001\",\n \"customer_name\": \"Yuki Tanaka\",\n \"permissible_purpose\": \"TENANCY_SCREENING\",\n \"expires_at\": \"2025-12-31T00:00:00Z\",\n \"revoked_at\": \"2025-03-31T10:45:00Z\",\n \"allowed_operator_ids\": [\n \"[email protected]\"\n ],\n \"created_at\": \"2025-03-31T10:30:00Z\",\n \"updated_at\": \"2025-03-31T10:45:00Z\"\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"detail\": \"Consent not found\"\n}"
}
}
}
Contract and execution notes
create_consentnormalizesexpires_atto timezone-aware UTC before callingregister_staff_credit_consent.revoke_consentaccepts an optionalrevoked_atfield and normalizes it to UTC when provided.- The file declares the
/credit-pullsroute for staff credit pulls, aligning the router prefix with the operator-led workflow described in the Japan credit documentation set.
Next.js Applicant API Route Proxies
The frontend app/api routes are transport adapters. They do not own the business rules for account coverage or transaction history; instead, they fan out to backend APIs, merge backend and locally stored application data when needed, and return a browser-friendly payload.
Account Coverage Proxy
File: frontend/app/api/v1/applicants/[id]/account-coverage/route.ts
This route validates the applicant id, resolves candidate backend base URLs from the request headers, and calls the backend applicant account-coverage endpoint with cache: "no-store". If one backend candidate returns 404, the route continues to the next candidate; backend request failures are translated into a Next.js JSON error response.
Handler method
| Method | Description |
|---|---|
GET |
Proxies the account coverage request to the backend and returns the first successful result |
Response shape
The route relays the backend schema documented in documents/account-coverage.md:
| Property | Type | Description |
|---|---|---|
application_id |
int |
Application id |
status |
string |
complete, incomplete, or unknown |
reported_accounts |
int |
Submitted accounts |
detected_accounts |
int |
Detected accounts |
missing_accounts |
int |
Missing accounts |
coverage_ratio |
`float \ | null` |
details |
list |
Per-connection results |
errors |
list |
Errors raised while detecting coverage |
Endpoint details
{
"title": "Get Applicant Account Coverage",
"description": "Frontend proxy that forwards account coverage requests to the backend applicant endpoint",
"method": "GET",
"baseUrl": "<FrontendAppBaseUrl>",
"endpoint": "/api/v1/applicants/{id}/account-coverage",
"headers": [],
"queryParams": [],
"pathParams": [
{
"name": "id",
"type": "string",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Coverage result returned from backend",
"body": "{\n \"application_id\": 123,\n \"status\": \"incomplete\",\n \"reported_accounts\": 2,\n \"detected_accounts\": 3,\n \"missing_accounts\": 1,\n \"coverage_ratio\": 0.67,\n \"details\": [\n {\n \"connection_name\": \"Example Bank\",\n \"institution_name\": \"Example Bank\",\n \"reported_accounts\": 2,\n \"detected_accounts\": 3,\n \"missing_accounts\": 1,\n \"status\": \"incomplete\"\n }\n ],\n \"errors\": []\n}"
},
"400": {
"description": "Invalid applicant id",
"body": "{\n \"detail\": \"Invalid applicant id.\"\n}"
},
"500": {
"description": "Backend API URL is not configured",
"body": "{\n \"detail\": \"Backend API URL is not configured. Set NEXT_PUBLIC_BACKEND_API_URL or BACKEND_API_URL.\"\n}"
},
"502": {
"description": "Backend API could not be reached",
"body": "{\n \"detail\": \"Failed to reach backend API. ...\"\n}"
}
}
}
Transactions Proxy
File: frontend/app/api/v1/applicants/[id]/transactions/route.ts
This route is the most opinionated proxy in the frontend API layer. It validates the applicant id and optional date range, tries a direct backend fetch, falls back to the backend list endpoint, then merges local stored applications and extracts transactions from metadata and connected_accounts. The final response is filtered by start_date and end_date and returned only when at least one transaction exists.
Handler method
| Method | Description |
|---|---|
GET |
Collects transactions from backend and stored sources, filters them by date, and returns the result set |
Response shape
The route returns a transaction bundle with these fields:
| Property | Type | Description |
|---|---|---|
applicant_id |
`int \ | string` |
start_date |
`string \ | null` |
end_date |
`string \ | null` |
transactions |
PaymentHistoryTransactionSummary[] |
Sorted transaction summaries |
A PaymentHistoryTransactionSummary entry is constructed from the fields the parser accepts:
| Property | Type | Description |
|---|---|---|
amount |
number |
Numeric transaction amount |
date |
string |
Transaction date string |
currency_code |
`string \ | null` |
status |
`string \ | null` |
account_name |
`string \ | null` |
connection_name |
`string \ | null` |
description |
`string \ | null` |
categories |
`string[] \ | null` |
provider |
`string \ | null` |
metadata |
Record<string, unknown> |
Original parsed record |
Endpoint details
{
"title": "Get Applicant Transactions",
"description": "Frontend route that merges backend, stored, and connected-account transactions for an applicant",
"method": "GET",
"baseUrl": "<FrontendAppBaseUrl>",
"endpoint": "/api/v1/applicants/{id}/transactions",
"headers": [],
"queryParams": [
{
"name": "start_date",
"type": "string",
"required": false
},
{
"name": "end_date",
"type": "string",
"required": false
}
],
"pathParams": [
{
"name": "id",
"type": "string",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Transaction list returned",
"body": "{\n \"applicant_id\": 123,\n \"start_date\": \"2025-01-01\",\n \"end_date\": \"2025-01-31\",\n \"transactions\": [\n {\n \"amount\": -20,\n \"date\": \"2025-01-15\",\n \"currency_code\": \"GBP\",\n \"status\": \"booked\",\n \"account_name\": \"Primary checking\",\n \"connection_name\": \"Example Bank\",\n \"description\": \"Coffee\",\n \"categories\": [\n \"food\",\n \"housing\"\n ],\n \"provider\": \"plaid\",\n \"metadata\": {\n \"amount\": -20,\n \"date\": \"2025-01-15\",\n \"description\": \"Coffee\"\n }\n }\n ]\n}"
},
"400": {
"description": "Invalid applicant id or invalid query parameters",
"body": "{\n \"detail\": \"Invalid query parameters.\"\n}"
},
"404": {
"description": "Application not found or no transaction history available",
"body": "{\n \"detail\": \"Application not found.\"\n}"
},
"502": {
"description": "Backend lookup failed",
"body": "{\n \"detail\": \"Failed to reach backend API. ...\"\n}"
}
}
}
Proxy execution notes
- The route uses
cache: "no-store"on backend fetches. - It accepts an applicant id from the URL, normalizes it with
zod, and rejects invalid identifiers with400. - It first tries a direct backend lookup, then a backend list lookup, then local stored data, and finally matches by
collectApplicationIdentifiers. - If no transactions remain after date filtering, it returns
404with a message that the applicant has no history yet.
Transaction proxy flow
sequenceDiagram
participant Browser as Browser
participant Route as Next Js Route
participant Backend as Backend API
participant Store as Local Stored Applications
Browser->>Route: GET /api/v1/applicants/id/transactions
Route->>Route: validate id and query params
Route->>Backend: direct applicant fetch
alt direct match found
Backend-->>Route: application
else direct match missing
Backend-->>Route: 404 or 422
end
Route->>Backend: list applicants
Backend-->>Route: applications list
Route->>Store: read stored applications
Store-->>Route: stored records
Route->>Route: collect identifiers and extract transactions
alt transactions found
Route-->>Browser: 200 transaction bundle
else no transactions found
Route-->>Browser: 404 no history
end
Internal Documentation Sources
The repository’s documentation files are not just guides; they are the contract source for the API surface.
documents/lita-consent-data-api.md
- Defines the consent-based data access and scoring contract.
- States that all data access requires explicit user consent.
- Describes customer-issued access credentials tied to a consent grant.
- Declares semantic versioning.
- Uses
X-Request-Idfor scoring idempotency on the customer-hosted scoring API. - Shows the customer-hosted scoring request and response shape with
version,request_id,score,decision,approved_limit,model, andreasons.
documents/us-api-v1.md
- Defines the US-specific consent, connection, token, data, feature, replay, and webhook contract.
- Namespaces the live contract under
/api/v1/us/. - Describes consent purpose enforcement, data-category restrictions, and connection states.
- States that backward-compatible changes increment minor versions.
- Requires
Authorization: Bearer <PARTNER_TOKEN>andX-Request-Idin the partner-to-Lita header contract shown in the document. - Defines error-code expectations such as
PURPOSE_NOT_ALLOWED,CATEGORY_NOT_ALLOWED,CONSENT_REVOKED, andREAUTH_REQUIRED.
documents/lita-implementation-overview.md
- Bridges the public contract to the current implementation.
- Confirms that the live routes are mounted under
/api/lita/v1. - Describes the persistence model names:
LitaConsentModelLitaAccessTokenModelLitaDataSnapshotModelLitaScoreDecisionModel
- States that token-gated routes enforce bearer authentication and revocation checks.
- Confirms idempotent scoring by
request_id. - Confirms that snapshots store JSON payloads with a
versionvalue.
Contract-to-code mapping
| Document | Runtime file it maps to | What the mapping controls |
|---|---|---|
documents/lita-consent-data-api.md |
backend/src/interface/lita_endpoints.py |
Consent lifecycle, data snapshots, scoring payload expectations |
documents/lita-implementation-overview.md |
backend/src/interface/lita_endpoints.py |
Actual route prefix, revocation checks, cached scoring behavior |
documents/us-api-v1.md |
backend/src/interface/open_banking_endpoints.py and the broader US contract layer |
Versioning, consent scope, data access, replay and webhook expectations |
State and Validation Semantics
Lita consent and token state
- Consent records are accepted only when
consent_referenceis unique. - Tokens are accepted only when present, not revoked, and not expired.
- Consent-linked data snapshots are accepted only when both the token and the consent are valid.
- Snapshot retrieval returns the most recent snapshot for the consent.
Scoring state
request_idis the cache key for prior decisions.- A cached decision is returned as-is without recomputing score or reasons.
- A new score is saved after computation so future identical
request_idsubmissions replay the same payload.
Open banking state
- Consents are filtered by operator allowlist before being returned.
- Consent linkage to a housing application is preserved through the repository and use-case layer.
- The Plaid token exchange path writes the returned access token and item id back onto the consent record.
Japan credit state
- Consent creation normalizes expiry timestamps.
- Consent revocation writes the revocation timestamp back into the stored response model.
- The operator allowlist is preserved in the response payload.
Error Handling
The API surfaces use explicit HTTP responses rather than silent fallthrough.
| Surface | Condition | Response |
|---|---|---|
| Lita consent creation | Duplicate consent_reference |
409 Conflict |
| Lita consent lookup | Missing consent | 404 Not Found |
| Lita token-gated routes | Missing, invalid, revoked, or expired token | 401 or 403 depending on the failure point |
| Lita token-gated routes | Missing, revoked, or expired consent | 403 or 404 depending on the failure point |
| Lita snapshot read | No snapshot exists | 404 Not Found |
| Open banking consent creation | Duplicate consent reference | 409 Conflict |
| Open banking link token / exchange | Missing consent, unauthorized operator, inactive consent, or upstream failure | 404, 403, 400, or 502 |
| Japan credit revoke | Missing consent | 404 Not Found |
| Frontend account coverage proxy | Invalid id or backend URL misconfiguration | 400 or 500 |
| Frontend transactions proxy | Invalid id, missing history, or backend failure | 400, 404, or 502 |
Testing Considerations
The repository includes tests and smoke flows that exercise the same contract boundaries documented above.
backend/tests/interface/test_lita_endpoints.py- consent creation
- token issuance
- snapshot write/read
- scoring idempotency
backend/tests/interface/test_open_banking_endpoints.py- open banking consent creation
- Plaid link token creation
- public token exchange
- auto refresh and manual refresh flows
documents/lita-testing-guide.md- manual curl flow for consent, token, snapshot, and score
- repeated score call to confirm idempotency
documents/account-coverage.md- account coverage endpoint contract and response shape
Integration Points
backend/src/main.pyregisters the interface routers that expose the public HTTP surfaces.backend/src/interface/lita_endpoints.pydepends onsrc.infra.mysql.lita_repository.LitaRepository.backend/src/interface/open_banking_endpoints.pydepends onBankGatewayandSQLOpenBankingConsentRepository.backend/src/interface/japan_credit_endpoints.pydepends on Japan credit repositories and the shared schema module.frontend/app/api/v1/applicants/[id]/account-coverage/route.tsandfrontend/app/api/v1/applicants/[id]/transactions/route.tsproxy browser requests to backend APIs and merge backend and stored data where needed.
Key Classes Reference
| Class | Responsibility |
|---|---|
backend/src/interface/lita_endpoints.py |
Lita consent, token, snapshot, and scoring contract models and handlers |
backend/src/interface/open_banking_endpoints.py |
Open banking consent and Plaid orchestration contract models and handlers |
backend/src/interface/japan_credit_endpoints.py |
Japan staff-initiated credit consent handlers |
backend/src/interface/schemas.py |
Shared Japan credit response schema |
frontend/app/api/v1/applicants/[id]/account-coverage/route.ts |
Account coverage proxy route |
frontend/app/api/v1/applicants/[id]/transactions/route.ts |
Transaction aggregation proxy route |
documents/lita-consent-data-api.md |
Customer-facing consent and scoring contract |
documents/us-api-v1.md |
US-specific customer-facing contract |
documents/lita-implementation-overview.md |
Implementation-oriented contract reference |