OBP-API Documentation

The Open Bank Project supports various financial service use cases. While the documentation is continuously expanding, key areas of focus include:

• Variable Recurring Payments (VRP): Managing recurring payment consents and workflows.
• Account Aggregation: Consolidating financial data from multiple sources.
• Payment Initiation Services (PIS): Facilitating the movement of funds.
• Account Information Services (AIS): Providing access to account data.
• Confirmation of Funds (CoF): Verifying available balances.
• Dynamic Consent Management: Managing user permissions dynamically.
• Multi-Bank Operations: Handling transactions across different banking institutions.

The OBP Roadmap is a living document organized by Theme and Horizon rather than fixed dates. Development priorities are driven by three factors: Client demand, Regulation (the only source of fixed dates), and Technology shifts (e.g., AI/MCP).

Horizons:

• Active: Currently in active development.
• Next: Committed direction, expected to start after current work or client engagement.
• Later: On the radar; subject to being pulled forward by demand or regulation.

For information on existing API functionality, refer to the API catalogs, glossary, and README. For architectural milestones that do not change API signatures, refer to completed_developments.md.

The ABAC (Attribute-Based Access Control) Rules Engine enables fine-grained, dynamic access control by executing Scala functions. It evaluates attributes belonging to users, banks, accounts, transactions, and customers to grant or deny access.

Core Components

• AbacRule: The data model for rule storage.
• AbacRuleProvider: Handles CRUD operations for rules.
• AbacRuleEngine: The core component responsible for compiling and executing Scala-based rules.
• AbacRuleEndpoints: The REST API layer for managing and executing rules.

OBP-Dispatch is a lightweight proxy/router designed to route API requests to different OBP-API implementations (e.g., routing traffic between the legacy Liftweb-based OBP-API, the new http4s-based v7.0.0 APIs, or OBP-Trading).

It allows for seamless implementation migration and the ability to host different versions of the API under a single entry point.

# Build
mvn clean package

# Run
java -jar target/OBP-API-Dispatch-1.0-SNAPSHOT-jar-with-dependencies.jar

# Docker
docker run -p 8080:8080 \
  -v /path/to/application.conf:/config/application.conf \
  obp-dispatch:latest

OBP-API supports two primary deployment models depending on your security and scale requirements:

Single Server Deployment

Best for simple setups or development. All components reside on one machine:

• OBP-API (HTTP4S)
• PostgreSQL
• Redis

Distributed Deployment with Akka Remote

Designed for high-security environments (e.g., separating the DMZ from the Secure Zone). This requires extra licensing and configuration. It splits the system into:

• API Layer (DMZ): Runs the OBP-API (HTTP Server) but has no direct database access.
• Data Layer (Secure Zone): Runs the OBP-API (Connector) which manages access to PostgreSQL and Core Banking Systems.
• Communication between layers is handled via Akka Remote.

Most objects in the ABAC context (except authenticatedUser, authenticatedUserAttributes, and authenticatedUserAuthContext) are wrapped in Scala Option types.

CRITICAL: Never call .get on an Option without first verifying it is defined, as this will throw a NoSuchElementException.

Recommended Patterns:

• Use .exists(condition) to check a property only if the object is present.
• Use .map(property).getOrElse(default) to safely access values.
• Use pattern matching (match { case Some(x) => ... }) for complex logic.
• Use .forall(condition) for negative constraints.

You can opt-in to tracking the 'who' and 'when' for specific fields within a Dynamic Entity (DE). When enabled, the server automatically stamps authoritative audit metadata for each write, and allows the writer to attach an opaque metadata object.

To enable this, add the trackProvenance keyword to your field definition. Alternatively, you can use trackProvenanceAllFields: true at the entity level to enable it for every field in that entity.

Note that trackProvenance is independent of access control; a field can be provenance-tracked regardless of whether it has restricted read or write roles.

When defining Dynamic Entities, you can specify which fields should be indexed to enable efficient querying. This is done via the indexed metadata in the entity definition.

Supported Metadata Options:

• indexed: true: Enables indexing for the field.
• index: "scalar" | "spatial": Specifies the index type. The default is "scalar".
• path: "a.b": Used for nested scalar fields (only applicable to scalar types).

Validation Rules:

• Spatial Indexing: index: "spatial" is only allowed on json fields (using GeoJSON).
• Scalar Indexing: If indexed: true is used on a json field, it must use index: "spatial". Otherwise, the definition will be rejected.
• Pathing: The path option is only valid when using a scalar type.

OBP-API uses Redis to track API call counts across different time windows.

Key Format

Rate limiting counters use the pattern {consumer_id}_{PERIOD}.

• Authorized Consumers: Use their unique consumer_id (e.g., consumer_abc123_PER_MINUTE).
• Anonymous Access: Uses the client's IP address (e.g., 192.168.1.100_PER_HOUR).

Value Format

Each key stores a string representation of the current call count (e.g., "42").

Time-To-Live (TTL) Mapping

Redis keys are automatically deleted when their TTL expires, resetting the window. The TTL is set to match the period duration:

// Example keys
consumer_abc123_PER_SECOND
consumer_abc123_PER_MINUTE
192.168.1.100_PER_HOUR