Skip to main content

​
B2C Customer Authentication Flow

This guide details the complete authentication flow for individual (B2C) customers in the FinHub platform v2.1. The new APIs provide enhanced security through proper session management, role-based access control, and streamlined two-factor authentication. The process supports both admin operations (for customer management) and customer operations (for transactions).

​
Key Improvements in v2.1

  1. Dual Token System: Separate tokens for admin and customer operations
  2. Session Management: X-Session-Id header for transaction security
  3. Role-Based Access: Clear separation between admin and customer permissions
  4. Enhanced 2FA: Support for multiple 2FA methods including TOTP
  5. Security Headers: X-Tenant-ID for multi-tenant isolation

​
Flow Overview

The following sequence diagram illustrates the enhanced B2C authentication process with v2.1 APIs:

​
Authentication Types

The v2.1 API supports two distinct authentication flows:

​
1. Admin Authentication

Used for customer management operations (registration, activation, verification)

​
2. Customer Authentication

Used for customer-initiated operations (transfers, beneficiary management, account access)

​
Detailed API Flow

​
Step 1: Admin Authentication (For Customer Management)

Admin authentication is required for managing customers. API Request: 
POST /api/v2.1/auth/admin/login
Content-Type: application/json
Request Body: 
{
  "username": "admin@tenant.com",
  "password": "AdminSecureP@ss",
  "tenantId": "finhub_tenant_001"
}
Response: 
{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "tenantId": "finhub_tenant_001",
    "permissions": [
      "customer:create",
      "customer:activate",
      "verification:approve"
    ]
  }
}

​
Step 2: Customer Authentication

Customers authenticate to access their accounts and perform transactions. API Request: 
POST /api/v2.1/auth/customer/login
Content-Type: application/json
X-Tenant-ID: {tenant_id}
Request Body: 
{
  "username": "john.doe@example.com",
  "password": "CustomerP@ssw0rd",
  "deviceInfo": {
    "deviceId": "device_abc123",
    "platform": "web",
    "userAgent": "Mozilla/5.0..."
  }
}
Response: 
{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "sessionId": "sess_xyz789abc123",
    "tokenType": "Bearer",
    "expiresIn": 1800,
    "customerId": "cust_abc123def456",
    "requires2FA": false,
    "sessionInfo": {
      "createdAt": "2025-01-23T10:00:00Z",
      "expiresAt": "2025-01-23T10:30:00Z",
      "ipAddress": "192.168.1.100",
      "deviceId": "device_abc123"
    }
  }
}
Key Features:
  • Session Management: Session ID required for all transaction operations
  • Device Tracking: Device information for security monitoring
  • Refresh Token: Allows token renewal without re-authentication
  • IP Validation: Session bound to IP for security

​
Step 3: Get Customer Profile with Wallet Details

After authentication, retrieve the customer’s profile including wallet information. API Request: 
GET /api/v2.1/customer/profile
Content-Type: application/json
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}
Response: 
{
  "data": {
    "customerId": "cust_abc123def456",
    "profile": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phoneNumber": "+12125551234",
      "nationality": "US"
    },
    "status": "ACTIVE",
    "verificationStatus": "VERIFIED",
    "riskLevel": "MEDIUM",
    "category": {
      "id": "cat_002",
      "name": "MEDIUM_RISK_INDIVIDUAL"
    },
    "walletInfo": {
      "walletId": "wal_def789ghi012",
      "iban": "FR1420041010050500013M02606",
      "currency": "EUR",
      "balance": {
        "available": "1500.50",
        "current": "1500.50",
        "locked": "0.00"
      }
    },
    "security": {
      "twoFactorEnabled": true,
      "twoFactorMethods": ["SMS", "EMAIL", "TOTP"],
      "preferredMethod": "TOTP"
    },
    "sessionInfo": {
      "lastLoginAt": "2025-01-23T10:00:00Z",
      "currentSessionStart": "2025-01-23T10:00:00Z",
      "loginCount": 45
    }
  }
}
Key Information:
  • Wallet Integration: Profile includes wallet and IBAN details
  • Risk Profile: Shows customer category and risk level
  • Security Settings: 2FA configuration and preferences
  • Session Context: Current session information

​
Step 4: Two-Factor Authentication (For Sensitive Operations)

The v2.1 API requires 2FA for sensitive operations like high-value transfers or security changes. Triggering 2FA: 
POST /api/v2.1/fintrans/{walletId}/order/prepare
If the operation requires 2FA, the response will indicate: 
{
  "error": {
    "code": "2FA_REQUIRED",
    "message": "This operation requires two-factor authentication",
    "requiredAction": "VERIFY_2FA",
    "verificationId": "2fa_req_abc123"
  }
}
API Request to send 2FA code: 
POST /api/v2.1/auth/2fa/send
Content-Type: application/json
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}
Request Body: 
{
  "verificationId": "2fa_req_abc123",
  "method": "TOTP"  // or "SMS", "EMAIL"
}
Response: 
{
  "data": {
    "verificationId": "2fa_req_abc123",
    "method": "TOTP",
    "status": "AWAITING_CODE",
    "expiresAt": "2025-01-23T10:15:00Z"
  }
}
API Request to verify 2FA code: 
POST /api/v2.1/auth/2fa/verify
Content-Type: application/json
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}
Request Body: 
{
  "verificationId": "2fa_req_abc123",
  "code": "123456",
  "trustDevice": true  // Optional: remember device for 30 days
}
Response: 
{
  "data": {
    "status": "VERIFIED",
    "sessionElevated": true,
    "elevatedUntil": "2025-01-23T10:45:00Z",
    "trustedDevice": {
      "deviceId": "device_abc123",
      "trustedUntil": "2025-02-22T10:15:00Z"
    },
    "canProceedWith": "ORIGINAL_OPERATION"
  }
}
Key Features:
  • Session Elevation: 2FA elevates session for 30 minutes
  • Device Trust: Option to trust device for future operations
  • Multiple Methods: Support for SMS, Email, and TOTP
  • Context-Aware: 2FA only required for sensitive operations

​
Step 5: Token Refresh

Use the refresh token to obtain new access tokens without re-authentication. API Request: 
POST /api/v2.1/auth/refresh
Content-Type: application/json
X-Tenant-ID: {tenant_id}
Request Body: 
{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "customerId": "cust_abc123def456"
}
Response: 
{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 1800
  }
}

​
Logout Process

Properly terminate the session and invalidate tokens. API Request: 
POST /api/v2.1/auth/logout
Content-Type: application/json
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}
Request Body: 
{
  "sessionId": "sess_xyz789abc123",
  "revokeAllSessions": false,  // Optional: logout from all devices
  "reason": "USER_INITIATED"
}
Response: 
{
  "data": {
    "status": "SUCCESS",
    "sessionsRevoked": 1,
    "message": "Successfully logged out"
  }
}
Cleanup Actions:
  • Server invalidates session and tokens
  • Clear all stored tokens and session data
  • Reset application state
  • Redirect to login page

​
Security Headers

All authenticated requests must include: 
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}  // For customer operations
X-Request-ID: {unique_request_id}  // For idempotency

​
Error Handling

Error CodeHTTP StatusDescription
INVALID_CREDENTIALS401Username or password incorrect
ACCOUNT_LOCKED423Account locked after failed attempts
ACCOUNT_SUSPENDED403Account suspended by admin
SESSION_EXPIRED401Session has expired
INVALID_SESSION401Session ID invalid or not found
TOKEN_EXPIRED401Access token has expired
REFRESH_TOKEN_EXPIRED401Refresh token has expired
INVALID_2FA_CODE4222FA code incorrect
2FA_CODE_EXPIRED4222FA code has expired
TOO_MANY_ATTEMPTS429Rate limit exceeded
DEVICE_NOT_TRUSTED403Device requires verification
IP_MISMATCH403Request from different IP

​
Error Response Example:

{
  "error": {
    "code": "ACCOUNT_LOCKED",
    "message": "Account locked due to multiple failed login attempts",
    "details": {
      "failedAttempts": 5,
      "lockedUntil": "2025-01-23T11:00:00Z",
      "unlockMethod": "TIME_BASED"  // or "ADMIN_UNLOCK", "EMAIL_VERIFICATION"
    },
    "requestId": "req_error_xyz789",
    "timestamp": "2025-01-23T10:30:00Z"
  }
}

​
Security Best Practices

  1. Token Storage:
    • Store access tokens in memory only
    • Store refresh tokens in secure storage (httpOnly cookies)
    • Never store tokens in localStorage for production
  2. Session Management:
    • Implement idle timeout (30 minutes)
    • Maximum session duration (8 hours)
    • Concurrent session limits
  3. Device Security:
    • Device fingerprinting
    • Trusted device management
    • New device notifications
  4. Rate Limiting:
    • 5 login attempts per 15 minutes
    • 3 2FA attempts per code
    • Progressive delays after failures
  5. Monitoring:
    • Log all authentication events
    • Alert on suspicious patterns
    • Geographic anomaly detection

​
Authentication Flows by Operation Type

​
Admin Operations

  • Customer Registration: Admin token only
  • Customer Activation: Admin token only
  • Verification Approval: Admin token only

​
Customer Operations

  • View Profile: Customer token + Session ID
  • Manage Beneficiaries: Customer token + Session ID
  • Execute Transfers: Customer token + Session ID + 2FA (if required)

​
Next Steps

After successful authentication:
  1. View Account Dashboard
  2. Manage Beneficiaries
  3. Execute Transfers
  4. Configure Security Settings
  5. Set Up Webhooks
⌘I