Regional Data Gateways Domain - US and JP Route Modules, Parity, and Region Specific Request Paths

Overview

The US and JP route modules expose the regional data-gateway surface for consent creation, authorization, token exchange, consent-scoped data access, feature computation, scoring replay, token lifecycle operations, and revocation. The same lifecycle is implemented twice, once under /api/v1/us and once under /api/v1/jp, so the API can keep region-specific pathing and data residency while preserving parity in consent, access, and replay flows.

The repository smoke surface validates that parity end-to-end. scripts/check-all-api-paths.sh drives the US and JP sequences with live HTTP calls, captures consent and token artifacts, and checks that both regions support the same operational stages: consent issuance, authorization, data access, feature computation, scoring, refresh, introspection, and revoke.

Architecture Overview

flowchart TD
    subgraph APIService [API Service]
        Server[API Server]
        USRoutes[usRoutes]
        JPRoutes[jpRoutes]
        USGuards[US route guards]
        JPGuards[JP route guards]
        USService[us-api service facade]
        JPService[jp-api service facade]
        Scoring[partner-scoring]
        Webhooks[Webhook delivery service]
    end

    subgraph SmokeChecks [Regional smoke checks]
        CheckAll[scripts check-all-api-paths.sh]
    end

    Server --> USRoutes
    Server --> JPRoutes
    USRoutes --> USGuards
    JPRoutes --> JPGuards
    USRoutes --> USService
    JPRoutes --> JPService
    USRoutes --> Scoring
    JPRoutes --> Scoring
    USRoutes --> Webhooks
    JPRoutes --> Webhooks
    CheckAll --> Server

Regional Path Parity

[!IMPORTANT] The US smoke path in scripts/check-all-api-paths.sh posts GENERAL_PERSONAL_FINANCE to POST /api/v1/us/consents, but purposeSchema in apps/api/src/routes/us/index.ts only accepts the seven US purposes listed in that schema. That request would be rejected by schema validation before the handler runs.

The two route modules implement the same lifecycle with region-specific prefixes and regionalized data handling.

Lifecycle Stage US Path JP Path Region Specific Behavior
Create consent POST /api/v1/us/consents POST /api/v1/jp/consents JP accepts appi_provision; both accept refresh permissions
Consent detail GET /api/v1/us/consents/:consentId GET /api/v1/jp/consents/:consentId Partner-auth only
Authorize GET /api/v1/us/consents/:consentId/authorize GET /api/v1/jp/consents/:consentId/authorize No auth guard on either path
Receipt GET /api/v1/us/consents/:consentId/receipt GET /api/v1/jp/consents/:consentId/receipt JP includes appi_provision in the receipt
Token exchange POST /api/v1/us/consents/:consentId/token POST /api/v1/jp/consents/:consentId/token Partner-auth only
Token refresh POST /api/v1/us/tokens/refresh POST /api/v1/jp/tokens/refresh Partner-auth only
Token introspection POST /api/v1/us/tokens/introspect POST /api/v1/jp/tokens/introspect Partner-auth only
Accounts GET /api/v1/us/data/accounts and GET /api/v1/us/consents/:consentId/data/accounts GET /api/v1/jp/data/accounts and GET /api/v1/jp/consents/:consentId/data/accounts Access-token gated; consent-scoped variants check path token consistency
Balances GET /api/v1/us/data/balances and GET /api/v1/us/consents/:consentId/data/balances GET /api/v1/jp/data/balances and GET /api/v1/jp/consents/:consentId/data/balances Same model across regions
Transactions GET /api/v1/us/data/transactions, GET /api/v1/us/data/transactions/sync, GET /api/v1/us/consents/:consentId/data/transactions GET /api/v1/jp/data/transactions, GET /api/v1/jp/data/transactions/sync, GET /api/v1/jp/consents/:consentId/data/transactions JP and US use the same transaction shape; consent-scoped variants paginate
Income GET /api/v1/us/data/income and GET /api/v1/us/consents/:consentId/data/income GET /api/v1/jp/data/income and GET /api/v1/jp/consents/:consentId/data/income Same output shape
Feature compute POST /api/v1/us/features/compute and POST /api/v1/us/consents/:consentId/features/compute POST /api/v1/jp/features/compute and POST /api/v1/jp/consents/:consentId/features/compute Dual mode in both regions: partner-auth job mode or access-token direct mode
Score GET /api/v1/us/consents/:consentId/score GET /api/v1/jp/consents/:consentId/score Both replay from stored evidence and call the scoring service
Evidence replay GET /api/v1/us/evidence/:evidenceRef GET /api/v1/jp/evidence/:evidenceRef Partner-auth only
KYC GET /api/v1/us/consents/:consentId/kyc GET /api/v1/jp/consents/:consentId/kyc Partner-auth only
Job status GET /api/v1/us/status/:jobId GET /api/v1/jp/status/:jobId Partner-auth only
Revoke POST /api/v1/us/consents/:consentId/revoke POST /api/v1/jp/consents/:consentId/revoke and DELETE /api/v1/jp/consents/:consentId JP exposes both revoke paths

Shared Data Shapes

Error Response

errorResponseSchema is the common error envelope used by both route modules.

Property Type Description
error.code string Stable machine code
error.message string Human-readable message
error.request_id string Request correlation identifier
error.retryable boolean Retry hint returned by the handler

Used by GET /consents/:consentId, GET /consents/:consentId/authorize, and GET /consents/:consentId/receipt.

Property Type Description
consent_id string Consent identifier
status string Current consent status
applicant_id `string \ null`
purpose string Consent purpose
redirect_url string Authorization redirect target
created_at string Creation timestamp
activated_at `string \ null`
expires_at string Expiration timestamp
revoked_at `string \ null`
connections Array Connection list for the consent
disclosure_version string Receipt version
appi_provision `Record<string, unknown> \ null`

Connection Entry

Property Type Description
connection_id string Connection identifier
provider string Display provider name
status string Connection status

Account Entry

Property Type Description
account_id string Account identifier
name string Account display name
type string Account type
mask string Masked identifier
institution string Financial institution

Balance Entry

Property Type Description
account_id string Account identifier
available number Available balance
current number Current balance
currency string Currency code

Transaction Entry

Property Type Description
transaction_id string Transaction identifier
account_id string Account identifier
posted_at string Posting timestamp
date string Date-only view used by paginated list endpoints
amount number Transaction amount
currency string Currency code
description string Transaction description
category string Transaction category
type string CREDIT or DEBIT

Income Summary

Property Type Description
method string Calculation method
gross_monthly number Gross monthly income
net_monthly number Net monthly income
currency string Currency code

Sync Response

Property Type Description
cursor string Sync cursor
added Array New transactions
modified Array Updated transactions
removed Array Removed transaction identifiers

Feature Compute Response

Property Type Description
evidence_ref string Stored evidence snapshot reference
features Record<string, number> Computed feature values

Job Record

Property Type Description
jobId string In-memory job identifier
status `PROCESSING \ COMPLETE \
consentId string Consent linked to the job
completedAt `string \ undefined`
error `string \ undefined`

Score Response

Property Type Description
consent_id string Consent identifier
applicant_id `string \ null`
score `number \ null`
score_range object Min and max score range
decision string Decision string
score_factors Array<string> Decision factors
evidence_ref `string \ null`
scored_at `string \ null`
model_version string Model version

KYC Response

Property Type Description
consent_id string Consent identifier
status string KYC state
checks.identity.status string Identity check status
checks.identity.method string Identity method
checks.sanctions.status string Sanctions check status
checks.sanctions.lists_screened Array<string> Screened lists
checks.pep.status string PEP check status
checks.aml.status string AML check status
checks.aml.risk_level string AML risk level
completed_at `string \ null`

Evidence Replay Response

Property Type Description
evidence_ref string Evidence reference
consent_id string Consent identifier
applicant_id `string \ null`
snapshot_version string Evidence schema version
created_at string Snapshot timestamp
score_inputs object Replay inputs
kyc_result object KYC result used for replay
delinquency_bucket string Derived delinquency bucket
features Record<string, number> Stored feature map

US Regional Data Gateway

apps/api/src/routes/us/index.ts

The US route module implements the regional API surface for US tenants. It uses partner-auth routes for consent management, token exchange, revocation, KYC, scoring, and replay, and access-token routes for consent-scoped and direct data access. The route handlers use the US service facade for storage and state transitions and the partner scoring service for score and replay operations.

Public Methods

Method Description
usRoutes Registers the US regional routes under the Fastify plugin

Route Guards and Helpers

Method Description
requireAccessToken Rejects requests that do not have a resolved US access context
requirePartnerAuth Rejects requests that already have a US access context and therefore are not partner-auth only
ensurePurpose Compares the optional x-purpose header with the access-context purpose
ensureCategory Checks that the requested data category is permitted by the access context
ensureConnection Loads the consent connection, degrades stale active connections, and rejects revoked or disconnected states
emitWebhook Fan-outs webhook events to every registered endpoint for the tenant
usJobStore Holds job results for partner-auth feature compute requests

Regional Request Flow

Stage US Behavior
Consent creation Partner-auth only, returns authorization redirect URLs
Data access Access-token only, with purpose and category checks
Feature compute Partner-auth job mode when consent_id is in the body, access-token direct mode otherwise
Score replay Reads stored evidence, calls fetchScoringDecision, emits decision.completed
Refresh/introspect Partner-auth only
Revoke Partner-auth only
{
    "title": "Create US Consent",
    "description": "Creates a US consent, returns the authorization redirect URL, and initializes the consent lifecycle",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/consents",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"applicant_id\": \"app_us_1001\",\n    \"purpose\": \"PERSONAL_FINANCE\",\n    \"data_categories\": [\n        \"ACCOUNTS\",\n        \"BALANCES\",\n        \"TRANSACTIONS\",\n        \"INCOME\",\n        \"CASHFLOW_FEATURES\"\n    ],\n    \"expires_in_days\": 30,\n    \"refresh_permissions\": {\n        \"enabled\": true,\n        \"max_refresh_per_day\": 8\n    },\n    \"user\": {\n        \"country\": \"US\"\n    }\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "201": {
            "description": "Consent created",
            "body": "{\n    \"consent_id\": \"cons_us_1001\",\n    \"authorization_url\": \"https://api.joinlita.com/api/v1/us/consents/cons_us_1001/authorize\",\n    \"redirect_url\": \"https://api.joinlita.com/api/v1/us/consents/cons_us_1001/authorize\",\n    \"status\": \"PENDING\",\n    \"expires_at\": \"2026-02-01T12:00:00.000Z\"\n}"
        },
        "401": {
            "description": "Partner auth required",
            "body": "{\n    \"error\": {\n        \"code\": \"TOKEN_NOT_ALLOWED\",\n        \"message\": \"Partner token required\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Get US Consent",
    "description": "Returns the current consent state and active connection list",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/:consentId",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_us_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent record",
            "body": "{\n    \"consent_id\": \"cons_us_1001\",\n    \"status\": \"ACTIVE\",\n    \"applicant_id\": \"app_us_1001\",\n    \"purpose\": \"PERSONAL_FINANCE\",\n    \"activated_at\": \"2026-01-02T00:00:00.000Z\",\n    \"expires_at\": \"2026-02-01T12:00:00.000Z\",\n    \"connections\": [\n        {\n            \"connection_id\": \"conn_us_1001\",\n            \"provider\": \"Financial Provider\",\n            \"status\": \"ACTIVE\"\n        }\n    ]\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"not_found\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Authorize US Consent",
    "description": "Returns the authorization code view used to exchange the consent for tokens",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/:consentId/authorize",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_us_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Authorization complete",
            "body": "{\n    \"consent_id\": \"cons_us_1001\",\n    \"purpose\": \"PERSONAL_FINANCE\",\n    \"data_categories\": [\n        \"accounts\",\n        \"balances\",\n        \"transactions\",\n        \"income\",\n        \"cashflow_features\"\n    ],\n    \"status\": \"ACTIVE\",\n    \"authorization_code\": \"ok\",\n    \"message\": \"Authorization complete. Exchange this code for an access token via POST /consents/:consentId/token\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"consent_not_found\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        },
        "409": {
            "description": "Consent expired or revoked",
            "body": "{\n    \"error\": {\n        \"code\": \"consent_revoked\",\n        \"message\": \"Consent has expired\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Get US Consent Receipt",
    "description": "Returns the consent receipt for partner audit workflows",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/:consentId/receipt",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_us_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Receipt document",
            "body": "{\n    \"consent_id\": \"cons_us_1001\",\n    \"purpose\": \"PERSONAL_FINANCE\",\n    \"data_categories\": [\n        \"accounts\",\n        \"balances\",\n        \"transactions\",\n        \"income\",\n        \"cashflow_features\"\n    ],\n    \"disclosure_version\": \"1.0.0\",\n    \"status\": \"ACTIVE\",\n    \"created_at\": \"2026-01-01T12:00:00.000Z\",\n    \"revoked_at\": null\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_NOT_FOUND\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Revoke US Consent",
    "description": "Revokes a consent and returns the revoked state",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/:consentId/revoke",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_us_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent revoked",
            "body": "{\n    \"consent_id\": \"cons_us_1001\",\n    \"status\": \"REVOKED\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_NOT_FOUND\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Exchange US Consent Token",
    "description": "Exchanges the authorization code for access and refresh tokens",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/:consentId/token",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_us_1001",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"authorization_code\": \"ok\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Token exchange result",
            "body": "{\n    \"access_token\": \"acc_us_1001\",\n    \"refresh_token\": \"ref_us_1001\",\n    \"expires_in\": 3600,\n    \"token_type\": \"Bearer\",\n    \"scope\": \"data:read data:write\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_NOT_FOUND\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Refresh US Access Token

{
    "title": "Refresh US Access Token",
    "description": "Refreshes an access token and can trigger a reauth webhook when the refresh limit is exceeded",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/tokens/refresh",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"refresh_token\": \"ref_us_1001\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Refreshed token pair",
            "body": "{\n    \"access_token\": \"acc_us_2001\",\n    \"refresh_token\": \"ref_us_2001\",\n    \"expires_in\": 3600,\n    \"token_type\": \"Bearer\",\n    \"scope\": \"data:read data:write\"\n}"
        },
        "400": {
            "description": "Refresh not allowed",
            "body": "{\n    \"error\": {\n        \"code\": \"REFRESH_LIMIT_EXCEEDED\",\n        \"message\": \"Refresh not allowed\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        },
        "401": {
            "description": "Partner auth required",
            "body": "{\n    \"error\": {\n        \"code\": \"TOKEN_NOT_ALLOWED\",\n        \"message\": \"Partner token required\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Introspect US Token

{
    "title": "Introspect US Token",
    "description": "Returns token activity and the consent scope attached to the token",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/tokens/introspect",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"token\": \"acc_us_1001\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Token introspection result",
            "body": "{\n    \"active\": true,\n    \"expires_at\": \"2026-01-01T13:00:00.000Z\",\n    \"consent_id\": \"cons_us_1001\",\n    \"purpose\": \"PERSONAL_FINANCE\",\n    \"data_categories\": [\n        \"accounts\",\n        \"balances\",\n        \"transactions\",\n        \"income\",\n        \"cashflow_features\"\n    ]\n}"
        }
    }
}

Get US Accounts

{
    "title": "Get US Accounts",
    "description": "Returns account records for the access-token consent context",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/data/accounts",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Account list",
            "body": "{\n    \"accounts\": [\n        {\n            \"account_id\": \"acct_us_1001\",\n            \"name\": \"Primary Checking\",\n            \"type\": \"checking\",\n            \"mask\": \"1234\",\n            \"institution\": \"Financial Provider\"\n        }\n    ]\n}"
        },
        "401": {
            "description": "Access token required",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        },
        "403": {
            "description": "Category or purpose denied",
            "body": "{\n    \"error\": {\n        \"code\": \"CATEGORY_NOT_ALLOWED\",\n        \"message\": \"accounts not permitted by consent\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Get US Consent Accounts",
    "description": "Returns accounts for a consent-scoped path and rejects consent-token mismatches",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/:consentId/data/accounts",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_us_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Account list",
            "body": "{\n    \"accounts\": [\n        {\n            \"account_id\": \"acct_us_1001\",\n            \"name\": \"Primary Checking\",\n            \"type\": \"checking\",\n            \"mask\": \"1234\",\n            \"institution\": \"Financial Provider\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Consent mismatch or category denied",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_MISMATCH\",\n        \"message\": \"Consent ID does not match token\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get US Balances

{
    "title": "Get US Balances",
    "description": "Returns available and current balances for the access-token consent context",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/data/balances",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Balance list",
            "body": "{\n    \"balances\": [\n        {\n            \"account_id\": \"acct_us_1001\",\n            \"available\": 1250.5,\n            \"current\": 1400.75,\n            \"currency\": \"USD\"\n        }\n    ]\n}"
        },
        "401": {
            "description": "Access token required",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Get US Consent Balances",
    "description": "Returns balances for a consent-scoped path and rejects consent-token mismatches",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/:consentId/data/balances",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_us_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Balance list",
            "body": "{\n    \"balances\": [\n        {\n            \"account_id\": \"acct_us_1001\",\n            \"available\": 1250.5,\n            \"current\": 1400.75,\n            \"currency\": \"USD\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Consent mismatch",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_MISMATCH\",\n        \"message\": \"Consent ID does not match token\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get US Transactions

{
    "title": "Get US Transactions",
    "description": "Returns transactions filtered by date for the access-token consent context",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/data/transactions",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "start_date",
            "value": "2026-01-01",
            "required": false
        },
        {
            "key": "end_date",
            "value": "2026-12-31",
            "required": false
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Transaction list",
            "body": "{\n    \"transactions\": [\n        {\n            \"transaction_id\": \"txn_us_1001\",\n            \"account_id\": \"acct_us_1001\",\n            \"posted_at\": \"2026-01-15T09:12:00Z\",\n            \"amount\": -42.5,\n            \"currency\": \"USD\",\n            \"description\": \"Coffee Shop\",\n            \"category\": \"food_and_drink\",\n            \"type\": \"DEBIT\"\n        }\n    ]\n}"
        },
        "401": {
            "description": "Access token required",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get US Transaction Sync

{
    "title": "Get US Transaction Sync",
    "description": "Returns a sync payload for transaction deltas",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/data/transactions/sync",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "cursor",
            "value": "demo",
            "required": false
        },
        {
            "key": "limit",
            "value": "50",
            "required": false
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Transaction delta page",
            "body": "{\n    \"cursor\": \"cur_50\",\n    \"added\": [\n        {\n            \"transaction_id\": \"txn_us_1001\",\n            \"account_id\": \"acct_us_1001\",\n            \"posted_at\": \"2026-01-15T09:12:00Z\",\n            \"amount\": -42.5,\n            \"currency\": \"USD\",\n            \"description\": \"Coffee Shop\",\n            \"category\": \"food_and_drink\"\n        }\n    ],\n    \"modified\": [\n        {\n            \"transaction_id\": \"txn_us_1002\",\n            \"account_id\": \"acct_us_1001\",\n            \"posted_at\": \"2026-01-16T09:12:00Z\",\n            \"amount\": 1200,\n            \"currency\": \"USD\",\n            \"description\": \"Payroll\",\n            \"category\": \"income\"\n        }\n    ],\n    \"removed\": [\n        {\n            \"transaction_id\": \"txn_us_1003\"\n        }\n    ]\n}"
        },
        "401": {
            "description": "Access token required",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Get US Consent Transactions",
    "description": "Returns paginated transactions for a consent-scoped path",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/:consentId/data/transactions",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "from_date",
            "value": "2026-01-01",
            "required": false
        },
        {
            "key": "to_date",
            "value": "2026-01-31",
            "required": false
        },
        {
            "key": "limit",
            "value": "25",
            "required": false
        },
        {
            "key": "cursor",
            "value": "cur_0",
            "required": false
        }
    ],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_us_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Paginated transaction response",
            "body": "{\n    \"data\": [\n        {\n            \"transaction_id\": \"txn_us_1001\",\n            \"date\": \"2026-01-15\",\n            \"amount\": -42.5,\n            \"currency\": \"USD\",\n            \"description\": \"Coffee Shop\",\n            \"category\": \"food_and_drink\",\n            \"type\": \"DEBIT\"\n        }\n    ],\n    \"next_cursor\": \"cur_25\",\n    \"total_count\": 1\n}"
        },
        "403": {
            "description": "Consent mismatch or category denied",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_MISMATCH\",\n        \"message\": \"Consent ID does not match token\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get US Income

{
    "title": "Get US Income",
    "description": "Returns monthly income totals for the access-token consent context",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/data/income",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Income summary",
            "body": "{\n    \"method\": \"DIRECT\",\n    \"gross_monthly\": 6500,\n    \"net_monthly\": 5200,\n    \"currency\": \"USD\"\n}"
        }
    }
}
{
    "title": "Get US Consent Income",
    "description": "Returns monthly income totals for a consent-scoped path",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/:consentId/data/income",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_us_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Income summary",
            "body": "{\n    \"method\": \"DIRECT\",\n    \"gross_monthly\": 6500,\n    \"net_monthly\": 5200,\n    \"currency\": \"USD\"\n}"
        }
    }
}

Compute US Features

{
    "title": "Compute US Features",
    "description": "Computes cashflow features. When consent_id is present, the route runs in partner-auth job mode and returns 202; otherwise it runs in access-token direct mode and returns 200",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/features/compute",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token_or_access_token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"consent_id\": \"cons_us_1001\",\n    \"feature_set\": \"US_CASHFLOW_V1\",\n    \"as_of\": \"2026-01-15T00:00:00Z\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "202": {
            "description": "Partner-auth job accepted",
            "body": "{\n    \"job_id\": \"job_a1b2c3d4e5f6\",\n    \"status\": \"PROCESSING\",\n    \"consent_id\": \"cons_us_1001\",\n    \"estimated_completion_ms\": 0\n}"
        },
        "200": {
            "description": "Direct compute result",
            "body": "{\n    \"evidence_ref\": \"evidence_us_1001\",\n    \"features\": {\n        \"monthly_income\": 5200,\n        \"avg_balance\": 1400.75,\n        \"overdraft_count\": 1,\n        \"cashflow_surplus\": 1450.25,\n        \"cashflow_inflow\": 4800,\n        \"cashflow_outflow\": 3349.75,\n        \"cashflow_net\": 1450.25\n    }\n}"
        }
    }
}

Get US Score

{
    "title": "Get US Score",
    "description": "Replays the stored evidence through the scoring provider and returns the derived decision",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/:consentId/score",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_us_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Score replay result",
            "body": "{\n    \"consent_id\": \"cons_us_1001\",\n    \"applicant_id\": \"app_us_1001\",\n    \"score\": 742,\n    \"score_range\": {\n        \"min\": 300,\n        \"max\": 850\n    },\n    \"decision\": \"APPROVE\",\n    \"score_factors\": [\n        \"CONSISTENT_PAYMENT_HISTORY\"\n    ],\n    \"evidence_ref\": \"evidence_us_1001\",\n    \"scored_at\": \"2026-01-15T12:00:00.000Z\",\n    \"model_version\": \"1.2.0\"\n}"
        },
        "422": {
            "description": "Consent not active or score not ready",
            "body": "{\n    \"error\": {\n        \"code\": \"score_not_ready\",\n        \"message\": \"Feature computation has not completed. Wait for score.completed webhook.\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        },
        "502": {
            "description": "Scoring provider unavailable",
            "body": "{\n    \"error\": {\n        \"code\": \"provider_unavailable\",\n        \"message\": \"Scoring provider error\",\n        \"request_id\": \"req_123\",\n        \"retryable\": true\n    }\n}"
        }
    }
}

Get US Evidence Replay

{
    "title": "Get US Evidence Replay",
    "description": "Rebuilds a score input view from a stored evidence snapshot",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/evidence/:evidenceRef",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "evidenceRef",
            "value": "evidence_us_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Evidence replay result",
            "body": "{\n    \"evidence_ref\": \"evidence_us_1001\",\n    \"consent_id\": \"cons_us_1001\",\n    \"applicant_id\": \"app_us_1001\",\n    \"snapshot_version\": \"1.2.0\",\n    \"created_at\": \"2026-01-15T12:00:00.000Z\",\n    \"score_inputs\": {\n        \"payment_behavior\": {\n            \"payments_observed\": 48,\n            \"avg_payment_delay_days\": 2,\n            \"late_payment_count_30d_plus\": 0\n        },\n        \"income\": {\n            \"monthly_net_income\": 5200,\n            \"income_stability_score\": 0.95\n        },\n        \"obligations\": {\n            \"total_monthly_obligations\": 1560,\n            \"obligation_to_income_ratio\": 0.3\n        }\n    },\n    \"kyc_result\": {\n        \"status\": \"PASSED\",\n        \"checks\": [\n            \"identity\",\n            \"sanctions\",\n            \"pep\"\n        ]\n    },\n    \"delinquency_bucket\": \"CURRENT\",\n    \"features\": {\n        \"monthly_income\": 5200,\n        \"avg_balance\": 1400.75,\n        \"overdraft_count\": 1,\n        \"cashflow_surplus\": 1450.25,\n        \"cashflow_inflow\": 4800,\n        \"cashflow_outflow\": 3349.75,\n        \"cashflow_net\": 1450.25\n    }\n}"
        },
        "404": {
            "description": "Evidence not found",
            "body": "{\n    \"error\": {\n        \"code\": \"EVIDENCE_NOT_FOUND\",\n        \"message\": \"Evidence not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get US KYC

{
    "title": "Get US KYC",
    "description": "Returns the derived KYC and AML check status for a consent",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/:consentId/kyc",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_us_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "KYC result",
            "body": "{\n    \"consent_id\": \"cons_us_1001\",\n    \"status\": \"PASSED\",\n    \"checks\": {\n        \"identity\": {\n            \"status\": \"PASSED\",\n            \"method\": \"document_biometric\"\n        },\n        \"sanctions\": {\n            \"status\": \"PASSED\",\n            \"lists_screened\": [\n                \"OFAC\",\n                \"UN\",\n                \"EU\"\n            ]\n        },\n        \"pep\": {\n            \"status\": \"PASSED\"\n        },\n        \"aml\": {\n            \"status\": \"PASSED\",\n            \"risk_level\": \"LOW\"\n        }\n    },\n    \"completed_at\": \"2026-01-15T12:00:00.000Z\"\n}"
        },
        "422": {
            "description": "Consent not active",
            "body": "{\n    \"error\": {\n        \"code\": \"consent_not_active\",\n        \"message\": \"KYC checks are run during feature computation. Activate the consent first.\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get US Job Status

{
    "title": "Get US Job Status",
    "description": "Returns the in-memory job state for partner-auth feature compute requests",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/status/:jobId",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "jobId",
            "value": "job_a1b2c3d4e5f6",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Job record",
            "body": "{\n    \"job_id\": \"job_a1b2c3d4e5f6\",\n    \"status\": \"COMPLETE\",\n    \"consent_id\": \"cons_us_1001\",\n    \"completed_at\": \"2026-01-15T12:00:00.000Z\",\n    \"error\": null\n}"
        },
        "404": {
            "description": "Job not found",
            "body": "{\n    \"error\": {\n        \"code\": \"not_found\",\n        \"message\": \"Job not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Replay US Decision

{
    "title": "Replay US Decision",
    "description": "Replays a stored evidence snapshot through the scoring service and returns the decision and reasons",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/us/decisions/replay",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"evidence_ref\": \"evidence_us_1001\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Replay result",
            "body": "{\n    \"evidence_ref\": \"evidence_us_1001\",\n    \"decision\": \"APPROVE\",\n    \"reasons\": [\n        \"CONSISTENT_PAYMENT_HISTORY\"\n    ]\n}"
        },
        "404": {
            "description": "Evidence or consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"EVIDENCE_NOT_FOUND\",\n        \"message\": \"Evidence not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

JP Regional Data Gateway

apps/api/src/routes/jp/index.ts

The JP route module mirrors the US lifecycle while adding JP-specific request handling, including APPI disclosure payloads, JP purpose normalization, refresh_permissions, JP feature job state, and KYC-aware score responses. It uses the JP service facade for consent and evidence persistence and emits the same webhook lifecycle events as the US module, with JP-specific pathing under /api/v1/jp.

Public Methods

Method Description
jpRoutes Registers the JP regional routes under the Fastify plugin

Route Guards and Helpers

Method Description
requireAccessToken Rejects requests that do not have a resolved JP access context
requirePartnerAuth Rejects requests that already have a JP access context and therefore are not partner-auth only
ensurePurpose Compares the optional x-purpose header with the access-context purpose
ensureCategory Checks that the requested data category is permitted by the access context
normalizePurpose Maps GENERAL_PERSONAL_FINANCE to PERSONAL_FINANCE
normalizeDataCategory Maps uppercase aliases and JP-specific categories to canonical JP categories
emitWebhook Fan-outs webhook events to every registered endpoint for the tenant
ensureConnection Loads the consent connection, degrades stale active connections, and rejects revoked or disconnected states
jpJobStore Holds job results for partner-auth feature compute requests

JP Specific Behavior

Stage JP Behavior
Consent creation Accepts appi_provision and refresh_permissions
Purpose normalization Converts GENERAL_PERSONAL_FINANCE into PERSONAL_FINANCE
Category normalization Treats payment_behavior and obligations as cashflow_features
Receipt Returns appi_provision when present
Feature compute Emits both features.computed and score.completed in partner-auth job mode
Decision replay Uses the same evidence replay shape as the US module
Revoke Supports both POST /revoke and DELETE /consents/:consentId
{
    "title": "Create JP Consent",
    "description": "Creates a JP consent, returns the authorization redirect URL, and accepts APPI disclosure data",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"applicant_id\": \"app_jp_1001\",\n    \"purpose\": \"GENERAL_PERSONAL_FINANCE\",\n    \"data_categories\": [\n        \"ACCOUNTS\",\n        \"BALANCES\",\n        \"TRANSACTIONS\",\n        \"INCOME\",\n        \"CASHFLOW_FEATURES\"\n    ],\n    \"expires_in_days\": 30,\n    \"refresh_permissions\": {\n        \"enabled\": true,\n        \"max_refresh_per_day\": 8\n    },\n    \"user\": {\n        \"country\": \"JP\"\n    },\n    \"appi_provision\": {\n        \"disclosure_language\": \"ja-JP\",\n        \"version\": \"2026-01\"\n    }\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "201": {
            "description": "Consent created",
            "body": "{\n    \"consent_id\": \"cons_jp_1001\",\n    \"authorization_url\": \"https://api.joinlita.com/api/v1/jp/consents/cons_jp_1001/authorize\",\n    \"redirect_url\": \"https://api.joinlita.com/api/v1/jp/consents/cons_jp_1001/authorize\",\n    \"status\": \"PENDING\",\n    \"expires_at\": \"2026-02-01T12:00:00.000Z\"\n}"
        },
        "401": {
            "description": "Partner auth required",
            "body": "{\n    \"error\": {\n        \"code\": \"TOKEN_NOT_ALLOWED\",\n        \"message\": \"Partner token required\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Get JP Consent",
    "description": "Returns the current consent state and active connection list for JP",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_jp_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent record",
            "body": "{\n    \"consent_id\": \"cons_jp_1001\",\n    \"status\": \"ACTIVE\",\n    \"applicant_id\": \"app_jp_1001\",\n    \"purpose\": \"PERSONAL_FINANCE\",\n    \"activated_at\": \"2026-01-02T00:00:00.000Z\",\n    \"expires_at\": \"2026-02-01T12:00:00.000Z\",\n    \"connections\": [\n        {\n            \"connection_id\": \"conn_jp_1001\",\n            \"provider\": \"Financial Provider\",\n            \"status\": \"ACTIVE\"\n        }\n    ]\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"not_found\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Authorize JP Consent",
    "description": "Returns the authorization code view used to exchange the consent for tokens",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/authorize",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_jp_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Authorization complete",
            "body": "{\n    \"consent_id\": \"cons_jp_1001\",\n    \"purpose\": \"PERSONAL_FINANCE\",\n    \"data_categories\": [\n        \"accounts\",\n        \"balances\",\n        \"transactions\",\n        \"income\",\n        \"cashflow_features\"\n    ],\n    \"status\": \"ACTIVE\",\n    \"authorization_code\": \"ok\",\n    \"message\": \"Authorization complete. Exchange this code for an access token via POST /consents/:consentId/token\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"consent_not_found\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        },
        "409": {
            "description": "Consent expired or revoked",
            "body": "{\n    \"error\": {\n        \"code\": \"consent_revoked\",\n        \"message\": \"Consent has expired\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Get JP Consent Receipt",
    "description": "Returns the JP consent receipt including APPI provision data",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/receipt",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_jp_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Receipt document",
            "body": "{\n    \"consent_id\": \"cons_jp_1001\",\n    \"purpose\": \"PERSONAL_FINANCE\",\n    \"data_categories\": [\n        \"accounts\",\n        \"balances\",\n        \"transactions\",\n        \"income\",\n        \"cashflow_features\"\n    ],\n    \"disclosure_version\": \"1.0.0\",\n    \"status\": \"ACTIVE\",\n    \"created_at\": \"2026-01-01T12:00:00.000Z\",\n    \"revoked_at\": null,\n    \"appi_provision\": {\n        \"disclosure_language\": \"ja-JP\",\n        \"version\": \"2026-01\"\n    }\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_NOT_FOUND\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Revoke JP Consent",
    "description": "Revokes a JP consent and returns the revoked state",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/revoke",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_jp_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent revoked",
            "body": "{\n    \"consent_id\": \"cons_jp_1001\",\n    \"status\": \"REVOKED\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"not_found\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Delete JP Consent",
    "description": "Deletes a JP consent through the alternate revoke path",
    "method": "DELETE",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_jp_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent revoked",
            "body": "{\n    \"consent_id\": \"cons_jp_1001\",\n    \"status\": \"REVOKED\",\n    \"revoked_at\": \"2026-01-15T12:00:00.000Z\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"not_found\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Exchange JP Consent Token",
    "description": "Exchanges the authorization code for access and refresh tokens",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/token",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_jp_1001",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"authorization_code\": \"ok\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Token exchange result",
            "body": "{\n    \"access_token\": \"acc_jp_1001\",\n    \"refresh_token\": \"ref_jp_1001\",\n    \"expires_in\": 3600,\n    \"token_type\": \"Bearer\",\n    \"scope\": \"data:read data:write\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_NOT_FOUND\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Refresh JP Access Token

{
    "title": "Refresh JP Access Token",
    "description": "Refreshes an access token and can trigger a reauth webhook when the refresh limit is exceeded",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/tokens/refresh",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"refresh_token\": \"ref_jp_1001\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Refreshed token pair",
            "body": "{\n    \"access_token\": \"acc_jp_2001\",\n    \"refresh_token\": \"ref_jp_2001\",\n    \"expires_in\": 3600,\n    \"token_type\": \"Bearer\",\n    \"scope\": \"data:read data:write\"\n}"
        },
        "400": {
            "description": "Refresh not allowed",
            "body": "{\n    \"error\": {\n        \"code\": \"REFRESH_LIMIT_EXCEEDED\",\n        \"message\": \"Refresh not allowed\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        },
        "401": {
            "description": "Partner auth required",
            "body": "{\n    \"error\": {\n        \"code\": \"TOKEN_NOT_ALLOWED\",\n        \"message\": \"Partner token required\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Introspect JP Token

{
    "title": "Introspect JP Token",
    "description": "Returns token activity and the consent scope attached to the token",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/tokens/introspect",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"token\": \"acc_jp_1001\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Token introspection result",
            "body": "{\n    \"active\": true,\n    \"expires_at\": \"2026-01-01T13:00:00.000Z\",\n    \"consent_id\": \"cons_jp_1001\",\n    \"purpose\": \"PERSONAL_FINANCE\",\n    \"data_categories\": [\n        \"accounts\",\n        \"balances\",\n        \"transactions\",\n        \"income\",\n        \"cashflow_features\"\n    ]\n}"
        }
    }
}

Get JP Accounts

{
    "title": "Get JP Accounts",
    "description": "Returns account records for the access-token consent context",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/data/accounts",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Account list",
            "body": "{\n    \"accounts\": [\n        {\n            \"account_id\": \"acct_jp_1001\",\n            \"name\": \"Primary Checking\",\n            \"type\": \"checking\",\n            \"mask\": \"1234\",\n            \"institution\": \"Financial Provider\"\n        }\n    ]\n}"
        }
    }
}
{
    "title": "Get JP Consent Accounts",
    "description": "Returns accounts for a consent-scoped path and rejects consent-token mismatches",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/data/accounts",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_jp_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Account list",
            "body": "{\n    \"accounts\": [\n        {\n            \"account_id\": \"acct_jp_1001\",\n            \"name\": \"Primary Checking\",\n            \"type\": \"checking\",\n            \"mask\": \"1234\",\n            \"institution\": \"Financial Provider\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Consent mismatch",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_MISMATCH\",\n        \"message\": \"Consent ID does not match token\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get JP Balances

{
    "title": "Get JP Balances",
    "description": "Returns available and current balances for the access-token consent context",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/data/balances",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Balance list",
            "body": "{\n    \"balances\": [\n        {\n            \"account_id\": \"acct_jp_1001\",\n            \"available\": 1250.5,\n            \"current\": 1400.75,\n            \"currency\": \"JPY\"\n        }\n    ]\n}"
        }
    }
}
{
    "title": "Get JP Consent Balances",
    "description": "Returns balances for a consent-scoped path and rejects consent-token mismatches",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/data/balances",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_jp_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Balance list",
            "body": "{\n    \"balances\": [\n        {\n            \"account_id\": \"acct_jp_1001\",\n            \"available\": 1250.5,\n            \"current\": 1400.75,\n            \"currency\": \"JPY\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Consent mismatch",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_MISMATCH\",\n        \"message\": \"Consent ID does not match token\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get JP Transactions

{
    "title": "Get JP Transactions",
    "description": "Returns transactions filtered by date for the access-token consent context",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/data/transactions",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "from",
            "value": "2026-01-01",
            "required": false
        },
        {
            "key": "to",
            "value": "2026-12-31",
            "required": false
        },
        {
            "key": "start_date",
            "value": "2026-01-01",
            "required": false
        },
        {
            "key": "end_date",
            "value": "2026-12-31",
            "required": false
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Transaction list",
            "body": "{\n    \"transactions\": [\n        {\n            \"transaction_id\": \"txn_jp_1001\",\n            \"account_id\": \"acct_jp_1001\",\n            \"posted_at\": \"2026-01-15T09:12:00Z\",\n            \"amount\": -4200,\n            \"currency\": \"JPY\",\n            \"description\": \"Coffee Shop\",\n            \"category\": \"food_and_drink\",\n            \"type\": \"DEBIT\"\n        }\n    ]\n}"
        }
    }
}

Get JP Transaction Sync

{
    "title": "Get JP Transaction Sync",
    "description": "Returns a sync payload for transaction deltas",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/data/transactions/sync",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "cursor",
            "value": "demo",
            "required": false
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Transaction delta page",
            "body": "{\n    \"cursor\": \"cursor_1700000000000\",\n    \"added\": [\n        {\n            \"transaction_id\": \"txn_jp_1001\",\n            \"account_id\": \"acct_jp_1001\",\n            \"posted_at\": \"2026-01-15T09:12:00Z\",\n            \"amount\": -4200,\n            \"currency\": \"JPY\",\n            \"description\": \"Coffee Shop\",\n            \"category\": \"food_and_drink\"\n        }\n    ],\n    \"modified\": [\n        {\n            \"transaction_id\": \"txn_jp_1002\",\n            \"account_id\": \"acct_jp_1001\",\n            \"posted_at\": \"2026-01-16T09:12:00Z\",\n            \"amount\": 180000,\n            \"currency\": \"JPY\",\n            \"description\": \"Payroll\",\n            \"category\": \"income\"\n        }\n    ],\n    \"removed\": [\n        {\n            \"transaction_id\": \"txn_jp_1003\"\n        }\n    ]\n}"
        }
    }
}
{
    "title": "Get JP Consent Transactions",
    "description": "Returns paginated transactions for a consent-scoped path",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/data/transactions",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "from_date",
            "value": "2026-01-01",
            "required": false
        },
        {
            "key": "to_date",
            "value": "2026-01-31",
            "required": false
        },
        {
            "key": "limit",
            "value": "25",
            "required": false
        },
        {
            "key": "cursor",
            "value": "cur_0",
            "required": false
        }
    ],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_jp_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Paginated transaction response",
            "body": "{\n    \"data\": [\n        {\n            \"transaction_id\": \"txn_jp_1001\",\n            \"date\": \"2026-01-15\",\n            \"amount\": -4200,\n            \"currency\": \"JPY\",\n            \"description\": \"Coffee Shop\",\n            \"category\": \"food_and_drink\",\n            \"type\": \"DEBIT\"\n        }\n    ],\n    \"next_cursor\": \"cur_25\",\n    \"total_count\": 1\n}"
        },
        "403": {
            "description": "Consent mismatch or category denied",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_MISMATCH\",\n        \"message\": \"Consent ID does not match token\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get JP Income

{
    "title": "Get JP Income",
    "description": "Returns monthly income totals for the access-token consent context",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/data/income",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Income summary",
            "body": "{\n    \"method\": \"DIRECT\",\n    \"gross_monthly\": 650000,\n    \"net_monthly\": 520000,\n    \"currency\": \"JPY\"\n}"
        }
    }
}
{
    "title": "Get JP Consent Income",
    "description": "Returns monthly income totals for a consent-scoped path",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/data/income",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_jp_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Income summary",
            "body": "{\n    \"method\": \"DIRECT\",\n    \"gross_monthly\": 650000,\n    \"net_monthly\": 520000,\n    \"currency\": \"JPY\"\n}"
        }
    }
}

Compute JP Features

{
    "title": "Compute JP Features",
    "description": "Computes cashflow features. When consent_id is present, the route runs in partner-auth job mode and returns 202; otherwise it runs in access-token direct mode and returns 200",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/features/compute",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token_or_access_token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"consent_id\": \"cons_jp_1001\",\n    \"feature_set\": \"JP_CASHFLOW_V1\",\n    \"as_of\": \"2026-01-15T00:00:00Z\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "202": {
            "description": "Partner-auth job accepted",
            "body": "{\n    \"job_id\": \"job_a1b2c3d4e5f6\",\n    \"status\": \"PROCESSING\",\n    \"consent_id\": \"cons_jp_1001\",\n    \"estimated_completion_ms\": 0\n}"
        },
        "200": {
            "description": "Direct compute result",
            "body": "{\n    \"evidence_ref\": \"evidence_jp_1001\",\n    \"features\": {\n        \"monthly_income\": 520000,\n        \"avg_balance\": 140075,\n        \"overdraft_count\": 1,\n        \"cashflow_surplus\": 145025,\n        \"cashflow_inflow\": 480000,\n        \"cashflow_outflow\": 334975,\n        \"cashflow_net\": 145025\n    }\n}"
        }
    }
}

Get JP Score

{
    "title": "Get JP Score",
    "description": "Replays the stored evidence through the scoring provider and returns the derived decision",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/score",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_jp_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Score replay result",
            "body": "{\n    \"consent_id\": \"cons_jp_1001\",\n    \"applicant_id\": \"app_jp_1001\",\n    \"score\": 742,\n    \"score_range\": {\n        \"min\": 300,\n        \"max\": 850\n    },\n    \"decision\": \"APPROVE\",\n    \"score_factors\": [\n        \"CONSISTENT_PAYMENT_HISTORY\"\n    ],\n    \"evidence_ref\": \"evidence_jp_1001\",\n    \"scored_at\": \"2026-01-15T12:00:00.000Z\",\n    \"model_version\": \"1.2.0\"\n}"
        },
        "422": {
            "description": "Consent not active or score not ready",
            "body": "{\n    \"error\": {\n        \"code\": \"consent_not_active\",\n        \"message\": \"The consent cons_jp_1001 is not in ACTIVE status.\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        },
        "502": {
            "description": "Scoring provider unavailable",
            "body": "{\n    \"error\": {\n        \"code\": \"provider_unavailable\",\n        \"message\": \"Scoring provider error\",\n        \"request_id\": \"req_123\",\n        \"retryable\": true\n    }\n}"
        }
    }
}

Get JP Evidence Replay

{
    "title": "Get JP Evidence Replay",
    "description": "Rebuilds a score input view from a stored evidence snapshot",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/evidence/:evidenceRef",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "evidenceRef",
            "value": "evidence_jp_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Evidence replay result",
            "body": "{\n    \"evidence_ref\": \"evidence_jp_1001\",\n    \"consent_id\": \"cons_jp_1001\",\n    \"applicant_id\": \"app_jp_1001\",\n    \"snapshot_version\": \"1.2.0\",\n    \"created_at\": \"2026-01-15T12:00:00.000Z\",\n    \"score_inputs\": {\n        \"payment_behavior\": {\n            \"payments_observed\": 48,\n            \"avg_payment_delay_days\": 2,\n            \"late_payment_count_30d_plus\": 0\n        },\n        \"income\": {\n            \"monthly_net_income\": 520000,\n            \"income_stability_score\": 0.95\n        },\n        \"obligations\": {\n            \"total_monthly_obligations\": 156000,\n            \"obligation_to_income_ratio\": 0.3\n        }\n    },\n    \"kyc_result\": {\n        \"status\": \"PASSED\",\n        \"checks\": [\n            \"identity\",\n            \"sanctions\",\n            \"pep\"\n        ]\n    },\n    \"delinquency_bucket\": \"CURRENT\",\n    \"features\": {\n        \"monthly_income\": 520000,\n        \"avg_balance\": 140075,\n        \"overdraft_count\": 1,\n        \"cashflow_surplus\": 145025,\n        \"cashflow_inflow\": 480000,\n        \"cashflow_outflow\": 334975,\n        \"cashflow_net\": 145025\n    }\n}"
        },
        "404": {
            "description": "Evidence not found",
            "body": "{\n    \"error\": {\n        \"code\": \"EVIDENCE_NOT_FOUND\",\n        \"message\": \"Evidence not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get JP KYC

{
    "title": "Get JP KYC",
    "description": "Returns the derived KYC and AML check status for a consent",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/kyc",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_jp_1001",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "KYC result",
            "body": "{\n    \"consent_id\": \"cons_jp_1001\",\n    \"status\": \"PASSED\",\n    \"checks\": {\n        \"identity\": {\n            \"status\": \"PASSED\",\n            \"method\": \"document_biometric\"\n        },\n        \"sanctions\": {\n            \"status\": \"PASSED\",\n            \"lists_screened\": [\n                \"OFAC\",\n                \"UN\",\n                \"EU\"\n            ]\n        },\n        \"pep\": {\n            \"status\": \"PASSED\"\n        },\n        \"aml\": {\n            \"status\": \"PASSED\",\n            \"risk_level\": \"LOW\"\n        }\n    },\n    \"completed_at\": \"2026-01-15T12:00:00.000Z\"\n}"
        },
        "422": {
            "description": "Consent not active",
            "body": "{\n    \"error\": {\n        \"code\": \"consent_not_active\",\n        \"message\": \"Consent not active\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get JP Job Status

{
    "title": "Get JP Job Status",
    "description": "Returns the in-memory job state for partner-auth feature compute requests",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/status/:jobId",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "jobId",
            "value": "job_a1b2c3d4e5f6",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Job record",
            "body": "{\n    \"job_id\": \"job_a1b2c3d4e5f6\",\n    \"status\": \"COMPLETE\",\n    \"consent_id\": \"cons_jp_1001\",\n    \"completed_at\": \"2026-01-15T12:00:00.000Z\",\n    \"error\": null\n}"
        },
        "404": {
            "description": "Job not found",
            "body": "{\n    \"error\": {\n        \"code\": \"not_found\",\n        \"message\": \"Job not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Replay JP Decision

{
    "title": "Replay JP Decision",
    "description": "Replays a stored evidence snapshot through the scoring service and returns the decision and reasons",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/api/v1/jp/decisions/replay",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"evidence_ref\": \"evidence_jp_1001\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Replay result",
            "body": "{\n    \"evidence_ref\": \"evidence_jp_1001\",\n    \"decision\": \"APPROVE\",\n    \"reasons\": [\n        \"CONSISTENT_PAYMENT_HISTORY\"\n    ]\n}"
        },
        "404": {
            "description": "Evidence or consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"EVIDENCE_NOT_FOUND\",\n        \"message\": \"Evidence not found\",\n        \"request_id\": \"req_123\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Webhook Delivery Service

The route modules fan out webhook notifications through listWebhookEndpoints and enqueueWebhookDelivery from @lita/webhooks. The emitWebhook helper is used in both regions, and the payloads are tenant-scoped.

Event Trigger
consent.activated After successful consent token exchange
connection.created After successful consent token exchange
consent.revoked After consent revocation
connection.degraded When ensureConnection downgrades a stale active connection or before replay on stale paths
connection.refreshed After touchConnection or touchJpConnection returns the refreshed connection
connection.reauth_required When token refresh hits the refresh limit
features.computed Partner-auth feature compute completes
score.completed Feature compute or scoring completion in the region flow
decision.completed Score replay returns a decision
sequenceDiagram
    participant H as Route handler
    participant E as emitWebhook
    participant L as listWebhookEndpoints
    participant Q as enqueueWebhookDelivery
    participant W as Webhook endpoints

    H->>E: eventType plus payload
    E->>L: tenantId
    L-->>E: endpoints
    loop every endpoint
        E->>Q: tenantId endpointId eventType payload
        Q-->>W: queued delivery
    end

Request Logging

The route modules use the Fastify reply logger for two failure classes:

Location Logged Data Purpose
Scoring callback catch block err plus the thrown error Captures provider callback failures
emitWebhook catch block err plus eventType Captures webhook queueing failures

The logging calls do not alter the HTTP response unless the surrounding handler chooses to return an error after catching the failure.

State Management

In-Memory Job Stores

Store Type Use
usJobStore Map<string, UsJobRecord> Tracks US partner-auth feature compute jobs
jpJobStore Map<string, JpJobRecord> Tracks JP partner-auth feature compute jobs

Connection Status Handling

ensureConnection reads the consent connection state and mutates stale active connections:

  • ACTIVE with a stale lastRefreshedAt value older than seven days is downgraded to DEGRADED
  • REAUTH_REQUIRED returns a 409 error with the reauth URL
  • DISCONNECTED returns a 409 provider-unavailable error

Status Values

  • Consent status: PENDING_USER_ACTION, ACTIVE, REVOKED
  • Connection status: ACTIVE, REAUTH_REQUIRED, DEGRADED, DISCONNECTED
  • Job status: PROCESSING, COMPLETE, FAILED

Error Handling

The route modules use the same error envelope shape and propagate request-scoped request.id values into the response. Errors are emitted with sendError, and the handlers return immediately after guard failures.

Error Case Typical Status
Missing partner token 401
Missing access token 401
Consent mismatch 403
Category not allowed 403
Connection not found 404
Consent not found 404
Job not found 404
Consent not active 422
Scoring provider unavailable 502
Refresh limit exceeded 400
Revoked consent on refresh 401

Dependencies

Route Module Dependencies

Dependency Used By Purpose
FastifyPluginAsync usRoutes, jpRoutes Route registration
zod Both route modules Request and response schemas
../../services/us-api.js US route module US consent, token, account, evidence, and connection operations
../../services/jp-api.js JP route module JP consent, token, account, evidence, and connection operations
../../services/partner-scoring.js Both route modules Score replay and decision retrieval
@lita/webhooks Both route modules Webhook endpoint lookup and delivery queueing
node:crypto Both route modules randomUUID for request IDs and job IDs
process.env.API_PUBLIC_BASE_URL Consent create handlers Authorization redirect construction
process.env.SCORING_CALLBACK_URL Score and replay handlers Fallback scoring callback configuration

Executable Regional Surface

[!NOTE] emitWebhook catches webhook fan-out failures, logs them with reply.log.error, and returns control to the handler without throwing. The request continues unless a later guard or business rule fails.

scripts/check-all-api-paths.sh validates the regional API surface by driving the same lifecycle in both regions. It starts with service readiness checks, then performs:

  • US consent creation
  • US token exchange
  • US receipt, data, feature, score, KYC, evidence, replay, refresh, introspection, and revoke checks
  • JP consent creation
  • JP token exchange
  • JP receipt, data, feature, score, KYC, evidence, replay, refresh, introspection, and revoke checks

The script uses curl and jq, records US_CONSENT, US_ACCESS, US_REFRESH, JP_CONSENT, JP_ACCESS, and JP_REFRESH, and exercises the exact regional paths under /api/v1/us and /api/v1/jp.

Key Classes Reference

Class Responsibility
us/index.ts US regional consent, token, data, scoring, KYC, evidence, and revocation routes
jp/index.ts JP regional consent, token, data, scoring, KYC, evidence, and revocation routes
check-all-api-paths.sh Executes the regional API smoke flow across both US and JP surfaces