OAuth & API Access PREMIUM

This guide covers how to integrate with your Business Continuity Suite using OAuth authentication and read-only API access. The Business Continuity Suite provides the same API endpoints as your cloud platform but with read-only access to synchronized loan origination data.

Overview

Each Business Continuity Suite instance includes a complete read-only API server that provides access to synchronized loan origination data. The API uses OAuth 2.0 Client Credentials flow for authentication, enabling secure integration with your internal systems while maintaining strict read-only access controls.

All API endpoints are documented using OpenAPI specifications, accessible at ~/open-api/ on your Business Continuity Suite instance. The API maintains compatibility with your cloud Banclo platform but restricts all operations to read-only access.

Available API Endpoints

Your Business Continuity Suite provides read-only access to the following data:

Loan Request Data

• GET /api/v1/loan-requests - List all synchronized loan requests
• GET /api/v1/loan-requests/{loanRequestId} - Get specific loan request details
• GET /api/v1/loan-requests/{loanRequestId}/audit-log - Access audit logs for compliance

Task Information

• GET /api/v1/loan-requests/{loanRequestId}/tasks - Get all tasks for a loan request
• GET /api/v1/loan-requests/{loanRequestId}/tasks/{taskId}/items/{itemId}/download - Download task attachments

Loan Bids and Analysis

• GET /api/v1/loan-requests/{loanRequestId}/bid-requests - Get loan bids
• GET /api/v1/loan-requests/{loanRequestId}/analysis - Get loan analysis data

Document Management

• GET /api/v1/loan-requests/{loanRequestId}/documents - List loan documents
• GET /api/v1/loan-requests/{loanRequestId}/documents/{documentId}/download - Download documents
• GET /api/v1/loan-requests/{loanRequestId}/spaces/ - Get document spaces
• GET /api/v1/loan-requests/{loanRequestId}/spaces/{spaceId}/documents/ - Get documents in spaces

Communication Records

• GET /api/v1/loan-requests/{loanRequestId}/guilds - Get communication guilds
• GET /api/v1/loan-requests/{loanRequestId}/guilds/{guildId}/channels/{channelId} - Get messages
• GET /api/v1/loan-requests/{loanRequestId}/comments - Get loan comments

Materialised Views

• GET /api/v1/loan-requests/{loanRequestId}/views/ - Get materialised views

Worksheets

• GET /api/v1/loan-requests/{loanRequestId}/worksheets - List worksheets
• GET /api/v1/loan-requests/{loanRequestId}/worksheets/{worksheetId} - Get specific worksheet

OAuth 2.0 Authentication

Creating OAuth Clients

OAuth clients are managed through the Business Continuity Suite's settings interface:

1. Navigate to Settings: Access your Business Continuity Suite web interface
2. OAuth Clients: Go to Settings → OAuth Clients
3. Create New Client: Click "New OAuth Client"
4. Configure Client:
   • Name: Descriptive name for your integration
   • Description: Optional description of the client's purpose
   • Scopes: Select required read-only permissions
   • Status: Enable/disable the client

Available OAuth Scopes

The Business Continuity Suite supports these read-only scopes:

• loans:read - Access loan requests and bids
• documents:read - Access documents and files
• bids:read - Access loan bid information
• tasks:read - Access task information
• analysis:read - Access analysis reports
• messages:read - Access messaging and communication records
• reports:read - Access reports and summaries
• audit:read - Access audit logs for compliance

Important: All scopes are read-only. No write, update, or delete operations are available through the Business Continuity Suite API.

Client Credentials Flow

The Business Continuity Suite uses OAuth 2.0 Client Credentials flow for server-to-server authentication:

1. Obtain Access Token

curl -X POST "https://your-continuity-suite:8083/api/v1/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "scope": "loans:read documents:read"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "loans:read documents:read"
}

2. Use Access Token

curl -X GET "https://your-continuity-suite:8083/api/v1/loan-requests" \
  -H "Authorization: Bearer your_access_token"

Integration Example

Python Integration

import requests
import time
from typing import Optional, Dict, Any, List

class BancloBusinessContinuityClient:
    def __init__(self, base_url: str, client_id: str, client_secret: str):
        self.base_url = base_url
        self.client_id = client_id
        self.client_secret = client_secret
        self.access_token: Optional[str] = None
        self.token_expiry: float = 0
        
    def authenticate(self) -> str:
        """Authenticate and obtain access token"""
        try:
            response = requests.post(f"{self.base_url}/api/v1/oauth/token", json={
                "grant_type": "client_credentials",
                "client_id": self.client_id,
                "client_secret": self.client_secret,
                "scope": "loans:read documents:read analysis:read"
            })
            response.raise_for_status()
            
            data = response.json()
            self.access_token = data['access_token']
            self.token_expiry = time.time() + data['expires_in'] - 60  # 1min buffer
            
            return self.access_token
        except requests.RequestException as e:
            print(f"Authentication failed: {e}")
            raise
    
    def _get_headers(self) -> Dict[str, str]:
        """Get headers with valid access token"""
        if not self.access_token or time.time() > self.token_expiry:
            self.authenticate()
        
        return {
            'Authorization': f'Bearer {self.access_token}',
            'Content-Type': 'application/json'
        }
    
    def get_loan_requests(self, **params) -> Dict[str, Any]:
        """Get list of loan requests with optional filters"""
        response = requests.get(
            f"{self.base_url}/api/v1/loan-requests",
            headers=self._get_headers(),
            params=params
        )
        response.raise_for_status()
        return response.json()
    
    def get_loan_request(self, loan_request_id: str) -> Dict[str, Any]:
        """Get specific loan request details"""
        response = requests.get(
            f"{self.base_url}/api/v1/loan-requests/{loan_request_id}",
            headers=self._get_headers()
        )
        response.raise_for_status()
        return response.json()
    
    def get_loan_request_tasks(self, loan_request_id: str) -> List[Dict[str, Any]]:
        """Get tasks for a loan request"""
        response = requests.get(
            f"{self.base_url}/api/v1/loan-requests/{loan_request_id}/tasks",
            headers=self._get_headers()
        )
        response.raise_for_status()
        return response.json()
    
    def get_loan_request_analysis(self, loan_request_id: str) -> List[Dict[str, Any]]:
        """Get analysis data for a loan request"""
        response = requests.get(
            f"{self.base_url}/api/v1/loan-requests/{loan_request_id}/analysis",
            headers=self._get_headers()
        )
        response.raise_for_status()
        return response.json()

# Usage Example
client = BancloBusinessContinuityClient(
    'https://your-continuity-suite.company.com:8083',
    'your_client_id',
    'your_client_secret'
)

# Get recent loan requests
loans = client.get_loan_requests(
    status=['BID', 'SANCTION'],
    limit=25,
    sortBy='createdAt',
    sortOrder='DESC'
)

print(f"Found {len(loans['loanRequests'])} loan requests")

# Get detailed information for each loan
for loan in loans['loanRequests'][:5]:  # Process first 5 loans
    loan_details = client.get_loan_request(loan['id'])
    tasks = client.get_loan_request_tasks(loan['id'])
    analysis = client.get_loan_request_analysis(loan['id'])
    
    print(f"Loan {loan['id']}: {len(tasks)} tasks, {len(analysis)} analysis reports")

API Documentation Access

Your Business Continuity Suite provides comprehensive API documentation:

OpenAPI Specification: Available at https://your-continuity-suite:8083/~/open-api/Interactive Testing: Swagger UI interface for exploring endpoints Schema Definitions: Complete data models and response formats Authentication Examples: OAuth integration code samples

The documentation is automatically synchronized with your deployment and always reflects the current API capabilities.

OAuth Client Management

Creating OAuth Clients

OAuth clients are created and managed through your Business Continuity Suite web interface:

1. Access Settings: Navigate to your Business Continuity Suite at https://your-instance:8083
2. OAuth Clients: Go to Settings → OAuth Clients
3. Create Client: Click "New OAuth Client"
4. Configure Permissions:
   • Name: Descriptive name for your integration
   • Description: Purpose of the OAuth client
   • Scopes: Select required read-only permissions
   • Status: Active/Inactive toggle

OAuth Client Configuration

When creating an OAuth client, you can configure:

Basic Information:

• Name: Required descriptive name
• Description: Optional detailed description

Security Settings:

• Client Credentials: Automatically generated secure client ID and secret
• Grant Types: Client Credentials flow (server-to-server)
• Active Status: Enable or disable the client

Permissions (Scopes): Select from available read-only scopes based on your integration needs.

Client Credentials Security

When you create an OAuth client:

1. Client ID: Automatically generated unique identifier
2. Client Secret: Cryptographically secure secret generated automatically
3. Secure Storage: Store credentials securely in your application configuration
4. Secret Rotation: Use the "Rotate Secret" function if credentials are compromised

Security Warning: Client secrets are only displayed once during creation. Store them securely as they cannot be retrieved later.

Health Monitoring

Health Check Endpoints

Monitor your Business Continuity Suite API:

• GET /health - General application health
• GET /ready - Readiness status for load balancers

Health Response Example:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "2.0.1",
  "database": "connected",
  "sync": "active",
  "uptime": "2h 15m"
}